diff --git a/Cargo.toml b/Cargo.toml index 58a63a37c..ff551e69c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -25,3 +25,7 @@ clippy = "*" # Always newest, since we use nightly [features] jit = ["evmjit"] evm_debug = [] + +[[bin]] +name = "client" +path = "src/bin/client/main.rs" diff --git a/src/account_diff.rs b/src/account_diff.rs index 3b01da522..1843c4381 100644 --- a/src/account_diff.rs +++ b/src/account_diff.rs @@ -5,8 +5,11 @@ use pod_account::*; /// Change in existance type. // TODO: include other types of change. pub enum Existance { + /// TODO [Gav Wood] Please document me Born, + /// TODO [Gav Wood] Please document me Alive, + /// TODO [Gav Wood] Please document me Died, } @@ -22,14 +25,20 @@ impl fmt::Display for Existance { } #[derive(Debug,Clone,PartialEq,Eq)] +/// TODO [Gav Wood] Please document me pub struct AccountDiff { + /// TODO [Gav Wood] Please document me pub balance: Diff, // Allowed to be Same + /// TODO [Gav Wood] Please document me pub nonce: Diff, // Allowed to be Same + /// TODO [Gav Wood] Please document me pub code: Diff, // Allowed to be Same + /// TODO [Gav Wood] Please document me pub storage: BTreeMap>,// Not allowed to be Same } impl AccountDiff { + /// TODO [Gav Wood] Please document me pub fn existance(&self) -> Existance { match self.balance { Diff::Born(_) => Existance::Born, @@ -38,6 +47,7 @@ impl AccountDiff { } } + /// TODO [Gav Wood] Please document me pub fn diff_pod(pre: Option<&PodAccount>, post: Option<&PodAccount>) -> Option { match (pre, post) { (None, Some(x)) => Some(AccountDiff { diff --git a/src/action_params.rs b/src/action_params.rs index 372927326..da1ae0ce0 100644 --- a/src/action_params.rs +++ b/src/action_params.rs @@ -30,6 +30,7 @@ pub struct ActionParams { } impl ActionParams { + /// TODO [Gav Wood] Please document me pub fn new() -> ActionParams { ActionParams { code_address: Address::new(), diff --git a/src/basic_types.rs b/src/basic_types.rs index 2466d8813..3d6fc2609 100644 --- a/src/basic_types.rs +++ b/src/basic_types.rs @@ -6,7 +6,10 @@ pub type LogBloom = H2048; /// Constant 2048-bit datum for 0. Often used as a default. pub static ZERO_LOGBLOOM: LogBloom = H2048([0x00; 256]); +/// TODO [Gav Wood] Please document me pub enum Seal { + /// TODO [Gav Wood] Please document me With, + /// TODO [Gav Wood] Please document me Without, } diff --git a/src/bin/client.rs b/src/bin/client/main.rs similarity index 100% rename from src/bin/client.rs rename to src/bin/client/main.rs diff --git a/src/block.rs b/src/block.rs index 25187883a..1ff326430 100644 --- a/src/block.rs +++ b/src/block.rs @@ -26,9 +26,13 @@ pub struct Block { /// A set of references to `Block` fields that are publicly accessible. pub struct BlockRefMut<'a> { + /// TODO [Gav Wood] Please document me pub header: &'a Header, + /// TODO [Gav Wood] Please document me pub state: &'a mut State, + /// TODO [Gav Wood] Please document me pub archive: &'a Vec, + /// TODO [Gav Wood] Please document me pub uncles: &'a Vec
, } diff --git a/src/blockchain.rs b/src/blockchain.rs index 516f18230..346fa61b5 100644 --- a/src/blockchain.rs +++ b/src/blockchain.rs @@ -15,18 +15,26 @@ use views::*; /// /// - `index` - an index where best common ancestor would be. pub struct TreeRoute { + /// TODO [debris] Please document me pub blocks: Vec, + /// TODO [debris] Please document me pub ancestor: H256, + /// TODO [debris] Please document me pub index: usize } /// Represents blockchain's in-memory cache size in bytes. #[derive(Debug)] pub struct CacheSize { + /// TODO [debris] Please document me pub blocks: usize, + /// TODO [debris] Please document me pub block_details: usize, + /// TODO [debris] Please document me pub transaction_addresses: usize, + /// TODO [debris] Please document me pub block_logs: usize, + /// TODO [debris] Please document me pub blocks_blooms: usize } diff --git a/src/builtin.rs b/src/builtin.rs index 9916cadb4..00d0bbeb5 100644 --- a/src/builtin.rs +++ b/src/builtin.rs @@ -63,6 +63,7 @@ impl Builtin { } } +/// TODO [Gav Wood] Please document me pub fn copy_to(src: &[u8], dest: &mut[u8]) { // NICE: optimise for i in 0..min(src.len(), dest.len()) { diff --git a/src/client.rs b/src/client.rs index cf57e6a07..b0801f097 100644 --- a/src/client.rs +++ b/src/client.rs @@ -49,9 +49,11 @@ impl fmt::Display for BlockChainInfo { /// Block queue status #[derive(Debug)] pub struct BlockQueueStatus { + /// TODO [arkpar] Please document me pub full: bool, } +/// TODO [arkpar] Please document me pub type TreeRoute = ::blockchain::TreeRoute; /// Blockchain database client. Owns and manages a blockchain and a block queue. @@ -106,13 +108,18 @@ pub trait BlockChainClient : Sync + Send { } #[derive(Default, Clone, Debug, Eq, PartialEq)] +/// TODO [Gav Wood] Please document me pub struct ClientReport { + /// TODO [Gav Wood] Please document me pub blocks_imported: usize, + /// TODO [Gav Wood] Please document me pub transactions_applied: usize, + /// TODO [Gav Wood] Please document me pub gas_processed: U256, } impl ClientReport { + /// TODO [Gav Wood] Please document me pub fn accrue_block(&mut self, block: &PreVerifiedBlock) { self.blocks_imported += 1; self.transactions_applied += block.transactions.len(); diff --git a/src/engine.rs b/src/engine.rs index 79857a404..d94797290 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -31,11 +31,14 @@ pub trait Engine : Sync + Send { /// Some intrinsic operation parameters; by default they take their value from the `spec()`'s `engine_params`. fn maximum_extra_data_size(&self) -> usize { decode(&self.spec().engine_params.get("maximumExtraDataSize").unwrap()) } + /// TODO [Gav Wood] Please document me fn maximum_uncle_count(&self) -> usize { 2 } + /// TODO [Gav Wood] Please document me fn account_start_nonce(&self) -> U256 { decode(&self.spec().engine_params.get("accountStartNonce").unwrap()) } /// Block transformation functions, before and after the transactions. fn on_new_block(&self, _block: &mut Block) {} + /// TODO [Gav Wood] Please document me fn on_close_block(&self, _block: &mut Block) {} // TODO: consider including State in the params for verification functions. @@ -55,6 +58,7 @@ pub trait Engine : Sync + Send { // TODO: Add flags for which bits of the transaction to check. // TODO: consider including State in the params. fn verify_transaction_basic(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) } + /// TODO [Gav Wood] Please document me fn verify_transaction(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) } /// Don't forget to call Super::populateFromParent when subclassing & overriding. @@ -63,8 +67,11 @@ pub trait Engine : Sync + Send { // TODO: builtin contract routing - to do this properly, it will require removing the built-in configuration-reading logic // from Spec into here and removing the Spec::builtins field. + /// TODO [Gav Wood] Please document me fn is_builtin(&self, a: &Address) -> bool { self.spec().builtins.contains_key(a) } + /// TODO [Gav Wood] Please document me fn cost_of_builtin(&self, a: &Address, input: &[u8]) -> U256 { self.spec().builtins.get(a).unwrap().cost(input.len()) } + /// TODO [Gav Wood] Please document me fn execute_builtin(&self, a: &Address, input: &[u8], output: &mut [u8]) { self.spec().builtins.get(a).unwrap().execute(input, output); } // TODO: sealing stuff - though might want to leave this for later. diff --git a/src/env_info.rs b/src/env_info.rs index c12fa653c..1246234ff 100644 --- a/src/env_info.rs +++ b/src/env_info.rs @@ -25,6 +25,7 @@ pub struct EnvInfo { } impl EnvInfo { + /// TODO [debris] Please document me pub fn new() -> EnvInfo { EnvInfo { number: 0, diff --git a/src/error.rs b/src/error.rs index 088367ae3..bc2bdfe97 100644 --- a/src/error.rs +++ b/src/error.rs @@ -5,15 +5,22 @@ use header::BlockNumber; use basic_types::LogBloom; #[derive(Debug, PartialEq, Eq)] +/// TODO [Gav Wood] Please document me pub struct Mismatch { + /// TODO [Gav Wood] Please document me pub expected: T, + /// TODO [Gav Wood] Please document me pub found: T, } #[derive(Debug, PartialEq, Eq)] +/// TODO [Gav Wood] Please document me pub struct OutOfBounds { + /// TODO [Gav Wood] Please document me pub min: Option, + /// TODO [Gav Wood] Please document me pub max: Option, + /// TODO [Gav Wood] Please document me pub found: T, } @@ -22,58 +29,112 @@ pub struct OutOfBounds { pub enum ExecutionError { /// Returned when there gas paid for transaction execution is /// lower than base gas required. - NotEnoughBaseGas { required: U256, got: U256 }, + /// TODO [Gav Wood] Please document me + NotEnoughBaseGas { + /// TODO [Gav Wood] Please document me + required: U256, + /// TODO [Gav Wood] Please document me + got: U256 + }, /// Returned when block (gas_used + gas) > gas_limit. /// /// If gas =< gas_limit, upstream may try to execute the transaction /// in next block. - BlockGasLimitReached { gas_limit: U256, gas_used: U256, gas: U256 }, + BlockGasLimitReached { + /// TODO [Gav Wood] Please document me + gas_limit: U256, + /// TODO [Gav Wood] Please document me + gas_used: U256, + /// TODO [Gav Wood] Please document me + gas: U256 + }, /// Returned when transaction nonce does not match state nonce. - InvalidNonce { expected: U256, got: U256 }, + InvalidNonce { + /// TODO [Gav Wood] Please document me + expected: U256, + /// TODO [Gav Wood] Please document me + got: U256 + }, /// Returned when cost of transaction (value + gas_price * gas) exceeds /// current sender balance. - NotEnoughCash { required: U512, got: U512 }, + NotEnoughCash { + /// TODO [Gav Wood] Please document me + required: U512, + /// TODO [Gav Wood] Please document me + got: U512 + }, /// Returned when internal evm error occurs. Internal } #[derive(Debug)] +/// TODO [Gav Wood] Please document me pub enum TransactionError { + /// TODO [Gav Wood] Please document me InvalidGasLimit(OutOfBounds), } #[derive(Debug, PartialEq, Eq)] +/// TODO [arkpar] Please document me pub enum BlockError { + /// TODO [Gav Wood] Please document me TooManyUncles(OutOfBounds), + /// TODO [Gav Wood] Please document me UncleWrongGeneration, + /// TODO [Gav Wood] Please document me ExtraDataOutOfBounds(OutOfBounds), + /// TODO [arkpar] Please document me InvalidSealArity(Mismatch), + /// TODO [arkpar] Please document me TooMuchGasUsed(OutOfBounds), + /// TODO [arkpar] Please document me InvalidUnclesHash(Mismatch), + /// TODO [arkpar] Please document me UncleTooOld(OutOfBounds), + /// TODO [arkpar] Please document me UncleIsBrother(OutOfBounds), + /// TODO [arkpar] Please document me UncleInChain(H256), + /// TODO [arkpar] Please document me UncleParentNotInChain(H256), + /// TODO [arkpar] Please document me InvalidStateRoot(Mismatch), + /// TODO [arkpar] Please document me InvalidGasUsed(Mismatch), + /// TODO [arkpar] Please document me InvalidTransactionsRoot(Mismatch), + /// TODO [arkpar] Please document me InvalidDifficulty(Mismatch), + /// TODO [arkpar] Please document me InvalidGasLimit(OutOfBounds), + /// TODO [arkpar] Please document me InvalidReceiptsStateRoot(Mismatch), + /// TODO [arkpar] Please document me InvalidTimestamp(OutOfBounds), + /// TODO [arkpar] Please document me InvalidLogBloom(Mismatch), + /// TODO [arkpar] Please document me InvalidEthashDifficulty(Mismatch), + /// TODO [arkpar] Please document me InvalidBlockNonce(Mismatch), + /// TODO [arkpar] Please document me InvalidParentHash(Mismatch), + /// TODO [arkpar] Please document me InvalidNumber(OutOfBounds), + /// TODO [arkpar] Please document me UnknownParent(H256), + /// TODO [Gav Wood] Please document me UnknownUncleParent(H256), } #[derive(Debug)] +/// TODO [arkpar] Please document me pub enum ImportError { + /// TODO [arkpar] Please document me Bad(Option), + /// TODO [arkpar] Please document me AlreadyInChain, + /// TODO [arkpar] Please document me AlreadyQueued, } @@ -89,10 +150,15 @@ pub type ImportResult = Result<(), ImportError>; #[derive(Debug)] /// General error type which should be capable of representing all errors in ethcore. pub enum Error { + /// TODO [Gav Wood] Please document me Util(UtilError), + /// TODO [Gav Wood] Please document me Block(BlockError), + /// TODO [Gav Wood] Please document me UnknownEngineName(String), + /// TODO [Gav Wood] Please document me Execution(ExecutionError), + /// TODO [Gav Wood] Please document me Transaction(TransactionError), } diff --git a/src/ethereum/denominations.rs b/src/ethereum/denominations.rs index a23c94b4c..093be89a7 100644 --- a/src/ethereum/denominations.rs +++ b/src/ethereum/denominations.rs @@ -1,17 +1,22 @@ use util::*; #[inline] +/// TODO [debris] Please document me pub fn ether() -> U256 { U256::exp10(18) } #[inline] +/// TODO [debris] Please document me pub fn finney() -> U256 { U256::exp10(15) } #[inline] +/// TODO [debris] Please document me pub fn szabo() -> U256 { U256::exp10(12) } #[inline] +/// TODO [debris] Please document me pub fn shannon() -> U256 { U256::exp10(9) } #[inline] +/// TODO [debris] Please document me pub fn wei() -> U256 { U256::exp10(0) } diff --git a/src/ethereum/ethash.rs b/src/ethereum/ethash.rs index 306b41e9c..aebee1e92 100644 --- a/src/ethereum/ethash.rs +++ b/src/ethereum/ethash.rs @@ -19,6 +19,7 @@ pub struct Ethash { } impl Ethash { + /// TODO [arkpar] Please document me pub fn new_boxed(spec: Spec) -> Box { Box::new(Ethash { spec: spec, diff --git a/src/ethereum/mod.rs b/src/ethereum/mod.rs index e97ac79a3..66bb7f356 100644 --- a/src/ethereum/mod.rs +++ b/src/ethereum/mod.rs @@ -3,7 +3,9 @@ //! Contains all Ethereum network specific stuff, such as denominations and //! consensus specifications. +/// TODO [Gav Wood] Please document me pub mod ethash; +/// TODO [Gav Wood] Please document me pub mod denominations; pub use self::ethash::*; diff --git a/src/evm/evm.rs b/src/evm/evm.rs index 696d49474..b90ea5f97 100644 --- a/src/evm/evm.rs +++ b/src/evm/evm.rs @@ -15,23 +15,31 @@ pub enum Error { /// `BadJumpDestination` is returned when execution tried to move /// to position that wasn't marked with JUMPDEST instruction BadJumpDestination { + /// TODO [Tomusdrw] Please document me destination: usize }, /// `BadInstructions` is returned when given instruction is not supported BadInstruction { + /// TODO [Tomusdrw] Please document me instruction: u8, }, /// `StackUnderflow` when there is not enough stack elements to execute instruction /// First parameter says how many elements were needed and the second how many were actually on Stack StackUnderflow { + /// TODO [Tomusdrw] Please document me instruction: &'static str, + /// TODO [Tomusdrw] Please document me wanted: usize, + /// TODO [Tomusdrw] Please document me on_stack: usize }, /// When execution would exceed defined Stack Limit OutOfStack { + /// TODO [Tomusdrw] Please document me instruction: &'static str, + /// TODO [Tomusdrw] Please document me wanted: usize, + /// TODO [Tomusdrw] Please document me limit: usize }, /// Returned on evm internal error. Should never be ignored during development. diff --git a/src/evm/ext.rs b/src/evm/ext.rs index 924db7a71..4d2471593 100644 --- a/src/evm/ext.rs +++ b/src/evm/ext.rs @@ -26,6 +26,7 @@ pub enum MessageCallResult { Failed } +/// TODO [debris] Please document me pub trait Ext { /// Returns a value for given key. fn storage_at(&self, key: &H256) -> H256; diff --git a/src/evm/factory.rs b/src/evm/factory.rs index 5b4d545ac..9f76d25ec 100644 --- a/src/evm/factory.rs +++ b/src/evm/factory.rs @@ -3,8 +3,11 @@ use std::fmt; use evm::Evm; #[derive(Clone)] +/// TODO [Tomusdrw] Please document me pub enum VMType { + /// TODO [Tomusdrw] Please document me Jit, + /// TODO [Tomusdrw] Please document me Interpreter } diff --git a/src/evm/mod.rs b/src/evm/mod.rs index 2ed9a1146..1426bc281 100644 --- a/src/evm/mod.rs +++ b/src/evm/mod.rs @@ -2,6 +2,7 @@ pub mod ext; pub mod evm; +/// TODO [Tomusdrw] Please document me pub mod interpreter; #[macro_use] pub mod factory; diff --git a/src/evm/schedule.rs b/src/evm/schedule.rs index f820f85e7..70edfceea 100644 --- a/src/evm/schedule.rs +++ b/src/evm/schedule.rs @@ -2,36 +2,67 @@ /// Definition of the cost schedule and other parameterisations for the EVM. pub struct Schedule { + /// TODO [Gav Wood] Please document me pub exceptional_failed_code_deposit: bool, + /// TODO [Gav Wood] Please document me pub have_delegate_call: bool, + /// TODO [Tomusdrw] Please document me pub stack_limit: usize, + /// TODO [Gav Wood] Please document me pub max_depth: usize, + /// TODO [Gav Wood] Please document me pub tier_step_gas: [usize; 8], + /// TODO [Gav Wood] Please document me pub exp_gas: usize, + /// TODO [Gav Wood] Please document me pub exp_byte_gas: usize, + /// TODO [Gav Wood] Please document me pub sha3_gas: usize, + /// TODO [Gav Wood] Please document me pub sha3_word_gas: usize, + /// TODO [Gav Wood] Please document me pub sload_gas: usize, + /// TODO [Gav Wood] Please document me pub sstore_set_gas: usize, + /// TODO [Gav Wood] Please document me pub sstore_reset_gas: usize, + /// TODO [Gav Wood] Please document me pub sstore_refund_gas: usize, + /// TODO [Gav Wood] Please document me pub jumpdest_gas: usize, + /// TODO [Gav Wood] Please document me pub log_gas: usize, + /// TODO [Gav Wood] Please document me pub log_data_gas: usize, + /// TODO [Gav Wood] Please document me pub log_topic_gas: usize, + /// TODO [Gav Wood] Please document me pub create_gas: usize, + /// TODO [Gav Wood] Please document me pub call_gas: usize, + /// TODO [Gav Wood] Please document me pub call_stipend: usize, + /// TODO [Gav Wood] Please document me pub call_value_transfer_gas: usize, + /// TODO [Gav Wood] Please document me pub call_new_account_gas: usize, + /// TODO [Gav Wood] Please document me pub suicide_refund_gas: usize, + /// TODO [Gav Wood] Please document me pub memory_gas: usize, + /// TODO [Gav Wood] Please document me pub quad_coeff_div: usize, + /// TODO [Gav Wood] Please document me pub create_data_gas: usize, + /// TODO [Gav Wood] Please document me pub tx_gas: usize, + /// TODO [Gav Wood] Please document me pub tx_create_gas: usize, + /// TODO [Gav Wood] Please document me pub tx_data_zero_gas: usize, + /// TODO [Gav Wood] Please document me pub tx_data_non_zero_gas: usize, + /// TODO [Gav Wood] Please document me pub copy_gas: usize, } diff --git a/src/extras.rs b/src/extras.rs index 8052af791..fb4748447 100644 --- a/src/extras.rs +++ b/src/extras.rs @@ -5,15 +5,21 @@ use rocksdb::{DB, Writable}; /// Represents index of extra data in database #[derive(Copy, Debug, Hash, Eq, PartialEq, Clone)] pub enum ExtrasIndex { + /// TODO [debris] Please document me BlockDetails = 0, + /// TODO [debris] Please document me BlockHash = 1, + /// TODO [debris] Please document me TransactionAddress = 2, + /// TODO [debris] Please document me BlockLogBlooms = 3, + /// TODO [debris] Please document me BlocksBlooms = 4 } /// trait used to write Extras data to db pub trait ExtrasWritable { + /// TODO [debris] Please document me fn put_extras(&self, hash: &K, value: &T) where T: ExtrasIndexable + Encodable, K: ExtrasSliceConvertable; @@ -21,10 +27,12 @@ pub trait ExtrasWritable { /// trait used to read Extras data from db pub trait ExtrasReadable { + /// TODO [debris] Please document me fn get_extras(&self, hash: &K) -> Option where T: ExtrasIndexable + Decodable, K: ExtrasSliceConvertable; + /// TODO [debris] Please document me fn extras_exists(&self, hash: &K) -> bool where T: ExtrasIndexable, K: ExtrasSliceConvertable; @@ -58,7 +66,9 @@ impl ExtrasReadable for DB { /// Implementations should convert arbitrary type to database key slice pub trait ExtrasSliceConvertable { + /// TODO [Gav Wood] Please document me fn to_extras_slice(&self, i: ExtrasIndex) -> H264; + /// TODO [debris] Please document me fn as_h256(&self) -> Option<&H256> { None } } @@ -86,6 +96,7 @@ impl ExtrasSliceConvertable for BlockNumber { /// Types implementing this trait can be indexed in extras database pub trait ExtrasIndexable { + /// TODO [debris] Please document me fn extras_index() -> ExtrasIndex; } @@ -98,9 +109,13 @@ impl ExtrasIndexable for H256 { /// Familial details concerning a block #[derive(Debug, Clone)] pub struct BlockDetails { + /// TODO [debris] Please document me pub number: BlockNumber, + /// TODO [debris] Please document me pub total_difficulty: U256, + /// TODO [debris] Please document me pub parent: H256, + /// TODO [debris] Please document me pub children: Vec } @@ -143,6 +158,7 @@ impl Encodable for BlockDetails { /// Log blooms of certain block #[derive(Clone)] pub struct BlockLogBlooms { + /// TODO [debris] Please document me pub blooms: Vec } @@ -176,6 +192,7 @@ impl Encodable for BlockLogBlooms { /// Neighboring log blooms on certain level pub struct BlocksBlooms { + /// TODO [debris] Please document me pub blooms: [H2048; 16] } @@ -223,7 +240,9 @@ impl Encodable for BlocksBlooms { /// Represents address of certain transaction within block #[derive(Clone)] pub struct TransactionAddress { + /// TODO [debris] Please document me pub block_hash: H256, + /// TODO [debris] Please document me pub index: u64 } diff --git a/src/header.rs b/src/header.rs index b09e0afcf..86710efcb 100644 --- a/src/header.rs +++ b/src/header.rs @@ -2,6 +2,7 @@ use util::*; use basic_types::*; use time::now_utc; +/// TODO [Gav Wood] Please document me pub type BlockNumber = u64; /// A block header. @@ -13,25 +14,41 @@ pub type BlockNumber = u64; #[derive(Debug, Clone)] pub struct Header { // TODO: make all private. + /// TODO [Gav Wood] Please document me pub parent_hash: H256, + /// TODO [arkpar] Please document me pub timestamp: u64, + /// TODO [debris] Please document me pub number: BlockNumber, + /// TODO [Gav Wood] Please document me pub author: Address, + /// TODO [debris] Please document me pub transactions_root: H256, + /// TODO [debris] Please document me pub uncles_hash: H256, + /// TODO [Gav Wood] Please document me pub extra_data: Bytes, + /// TODO [debris] Please document me pub state_root: H256, + /// TODO [debris] Please document me pub receipts_root: H256, + /// TODO [debris] Please document me pub log_bloom: LogBloom, + /// TODO [debris] Please document me pub gas_used: U256, + /// TODO [Gav Wood] Please document me pub gas_limit: U256, + /// TODO [debris] Please document me pub difficulty: U256, + /// TODO [arkpar] Please document me pub seal: Vec, + /// TODO [arkpar] Please document me pub hash: RefCell>, + /// TODO [Gav Wood] Please document me pub bare_hash: RefCell>, } @@ -61,32 +78,50 @@ impl Header { } } + /// TODO [Gav Wood] Please document me pub fn number(&self) -> BlockNumber { self.number } + /// TODO [Gav Wood] Please document me pub fn timestamp(&self) -> u64 { self.timestamp } + /// TODO [Gav Wood] Please document me pub fn author(&self) -> &Address { &self.author } + /// TODO [Gav Wood] Please document me pub fn extra_data(&self) -> &Bytes { &self.extra_data } + /// TODO [Gav Wood] Please document me pub fn state_root(&self) -> &H256 { &self.state_root } + /// TODO [Gav Wood] Please document me pub fn receipts_root(&self) -> &H256 { &self.receipts_root } + /// TODO [Gav Wood] Please document me pub fn gas_limit(&self) -> &U256 { &self.gas_limit } + /// TODO [Gav Wood] Please document me pub fn difficulty(&self) -> &U256 { &self.difficulty } + /// TODO [Gav Wood] Please document me pub fn seal(&self) -> &Vec { &self.seal } // TODO: seal_at, set_seal_at &c. + /// TODO [Gav Wood] Please document me pub fn set_number(&mut self, a: BlockNumber) { self.number = a; self.note_dirty(); } + /// TODO [Gav Wood] Please document me pub fn set_timestamp(&mut self, a: u64) { self.timestamp = a; self.note_dirty(); } + /// TODO [Gav Wood] Please document me pub fn set_timestamp_now(&mut self) { self.timestamp = now_utc().to_timespec().sec as u64; self.note_dirty(); } + /// TODO [Gav Wood] Please document me pub fn set_author(&mut self, a: Address) { if a != self.author { self.author = a; self.note_dirty(); } } + /// TODO [Gav Wood] Please document me pub fn set_extra_data(&mut self, a: Bytes) { if a != self.extra_data { self.extra_data = a; self.note_dirty(); } } + /// TODO [Gav Wood] Please document me pub fn set_gas_used(&mut self, a: U256) { self.gas_used = a; self.note_dirty(); } + /// TODO [Gav Wood] Please document me pub fn set_gas_limit(&mut self, a: U256) { self.gas_limit = a; self.note_dirty(); } + /// TODO [Gav Wood] Please document me pub fn set_difficulty(&mut self, a: U256) { self.difficulty = a; self.note_dirty(); } + /// TODO [Gav Wood] Please document me pub fn set_seal(&mut self, a: Vec) { self.seal = a; self.note_dirty(); } /// Get the hash of this header (sha3 of the RLP). @@ -120,6 +155,7 @@ impl Header { } // TODO: make these functions traity + /// TODO [Gav Wood] Please document me pub fn stream_rlp(&self, s: &mut RlpStream, with_seal: Seal) { s.append_list(13 + match with_seal { Seal::With => self.seal.len(), _ => 0 }); s.append(&self.parent_hash); @@ -142,12 +178,14 @@ impl Header { } } + /// TODO [Gav Wood] Please document me pub fn rlp(&self, with_seal: Seal) -> Bytes { let mut s = RlpStream::new(); self.stream_rlp(&mut s, with_seal); s.out() } + /// TODO [debris] Please document me pub fn rlp_sha3(&self, with_seal: Seal) -> H256 { self.rlp(with_seal).sha3() } } diff --git a/src/lib.rs b/src/lib.rs index f9795f324..f478cf75c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] #![feature(cell_extras)] #![feature(augmented_assignments)] #![feature(plugin)] @@ -90,31 +91,51 @@ extern crate evmjit; #[macro_use] extern crate ethcore_util as util; +/// TODO [Gav Wood] Please document me pub mod common; +/// TODO [Tomusdrw] Please document me pub mod basic_types; #[macro_use] pub mod evm; pub mod error; +/// TODO [Gav Wood] Please document me pub mod log_entry; +/// TODO [Gav Wood] Please document me pub mod env_info; +/// TODO [Gav Wood] Please document me pub mod pod_account; +/// TODO [Gav Wood] Please document me pub mod pod_state; +/// TODO [Gav Wood] Please document me pub mod account_diff; +/// TODO [Gav Wood] Please document me pub mod state_diff; +/// TODO [Gav Wood] Please document me pub mod engine; +/// TODO [Gav Wood] Please document me pub mod state; +/// TODO [Gav Wood] Please document me pub mod account; pub mod action_params; +/// TODO [debris] Please document me pub mod header; +/// TODO [Gav Wood] Please document me pub mod transaction; +/// TODO [Gav Wood] Please document me pub mod receipt; +/// TODO [Gav Wood] Please document me pub mod null_engine; +/// TODO [Gav Wood] Please document me pub mod builtin; +/// TODO [debris] Please document me pub mod spec; pub mod views; pub mod blockchain; +/// TODO [Gav Wood] Please document me pub mod extras; +/// TODO [arkpar] Please document me pub mod substate; +/// TODO [Gav Wood] Please document me pub mod service; pub mod executive; pub mod externalities; @@ -122,9 +143,14 @@ pub mod externalities; #[cfg(test)] mod tests; +/// TODO [arkpar] Please document me pub mod client; +/// TODO [arkpar] Please document me pub mod sync; +/// TODO [arkpar] Please document me pub mod block; +/// TODO [arkpar] Please document me pub mod verification; +/// TODO [debris] Please document me pub mod queue; pub mod ethereum; diff --git a/src/log_entry.rs b/src/log_entry.rs index cd4353874..a791b38a6 100644 --- a/src/log_entry.rs +++ b/src/log_entry.rs @@ -4,8 +4,11 @@ use basic_types::LogBloom; /// A single log's entry. #[derive(Debug,PartialEq,Eq)] pub struct LogEntry { + /// TODO [Gav Wood] Please document me pub address: Address, + /// TODO [Gav Wood] Please document me pub topics: Vec, + /// TODO [Gav Wood] Please document me pub data: Bytes, } diff --git a/src/null_engine.rs b/src/null_engine.rs index e673563b3..3b03508a2 100644 --- a/src/null_engine.rs +++ b/src/null_engine.rs @@ -11,6 +11,7 @@ pub struct NullEngine { } impl NullEngine { + /// TODO [Tomusdrw] Please document me pub fn new_boxed(spec: Spec) -> Box { Box::new(NullEngine{ spec: spec, diff --git a/src/pod_account.rs b/src/pod_account.rs index 29b43c0bf..81b8b1c44 100644 --- a/src/pod_account.rs +++ b/src/pod_account.rs @@ -4,9 +4,13 @@ use account::*; #[derive(Debug,Clone,PartialEq,Eq)] /// Genesis account data. Does not have a DB overlay cache. pub struct PodAccount { + /// TODO [Gav Wood] Please document me pub balance: U256, + /// TODO [Gav Wood] Please document me pub nonce: U256, + /// TODO [Gav Wood] Please document me pub code: Bytes, + /// TODO [Gav Wood] Please document me pub storage: BTreeMap, } @@ -27,6 +31,7 @@ impl PodAccount { } } + /// TODO [Gav Wood] Please document me pub fn rlp(&self) -> Bytes { let mut stream = RlpStream::new_list(4); stream.append(&self.nonce); diff --git a/src/pod_state.rs b/src/pod_state.rs index 68f057d9c..1ea8382a5 100644 --- a/src/pod_state.rs +++ b/src/pod_state.rs @@ -2,6 +2,7 @@ use util::*; use pod_account::*; #[derive(Debug,Clone,PartialEq,Eq)] +/// TODO [Gav Wood] Please document me pub struct PodState (BTreeMap); impl PodState { diff --git a/src/queue.rs b/src/queue.rs index 5803b3e5f..7c74b56d7 100644 --- a/src/queue.rs +++ b/src/queue.rs @@ -204,6 +204,7 @@ impl BlockQueue { verification.verified = new_verified; } + /// TODO [arkpar] Please document me pub fn drain(&mut self, max: usize) -> Vec { let mut verification = self.verification.lock().unwrap(); let count = min(max, verification.verified.len()); diff --git a/src/receipt.rs b/src/receipt.rs index a1b2fbe6f..403915fdc 100644 --- a/src/receipt.rs +++ b/src/receipt.rs @@ -5,13 +5,18 @@ use log_entry::LogEntry; /// Information describing execution of a transaction. #[derive(Debug)] pub struct Receipt { + /// TODO [Gav Wood] Please document me pub state_root: H256, + /// TODO [Gav Wood] Please document me pub gas_used: U256, + /// TODO [Gav Wood] Please document me pub log_bloom: LogBloom, + /// TODO [Gav Wood] Please document me pub logs: Vec, } impl Receipt { + /// TODO [Gav Wood] Please document me pub fn new(state_root: H256, gas_used: U256, logs: Vec) -> Receipt { Receipt { state_root: state_root, diff --git a/src/service.rs b/src/service.rs index 0d6acfd19..debabaafe 100644 --- a/src/service.rs +++ b/src/service.rs @@ -33,10 +33,12 @@ impl ClientService { }) } + /// TODO [arkpar] Please document me pub fn io(&mut self) -> &mut IoService { self.net_service.io() } + /// TODO [arkpar] Please document me pub fn client(&self) -> Arc> { self.client.clone() } diff --git a/src/spec.rs b/src/spec.rs index 2c112268f..086b76339 100644 --- a/src/spec.rs +++ b/src/spec.rs @@ -51,6 +51,7 @@ pub struct GenesisAccount { } impl GenesisAccount { + /// TODO [arkpar] Please document me pub fn rlp(&self) -> Bytes { let mut stream = RlpStream::new_list(4); stream.append(&self.nonce); @@ -66,27 +67,41 @@ impl GenesisAccount { #[derive(Debug)] pub struct Spec { // User friendly spec name + /// TODO [Gav Wood] Please document me pub name: String, // What engine are we using for this? + /// TODO [Gav Wood] Please document me pub engine_name: String, // Parameters concerning operation of the specific engine we're using. // Name -> RLP-encoded value + /// TODO [Gav Wood] Please document me pub engine_params: HashMap, // Builtin-contracts are here for now but would like to abstract into Engine API eventually. + /// TODO [Gav Wood] Please document me pub builtins: HashMap, // Genesis params. + /// TODO [Gav Wood] Please document me pub parent_hash: H256, + /// TODO [Gav Wood] Please document me pub author: Address, + /// TODO [Gav Wood] Please document me pub difficulty: U256, + /// TODO [Gav Wood] Please document me pub gas_limit: U256, + /// TODO [Gav Wood] Please document me pub gas_used: U256, + /// TODO [Gav Wood] Please document me pub timestamp: u64, + /// TODO [arkpar] Please document me pub extra_data: Bytes, + /// TODO [Gav Wood] Please document me pub genesis_state: HashMap, + /// TODO [Gav Wood] Please document me pub seal_fields: usize, + /// TODO [Gav Wood] Please document me pub seal_rlp: Bytes, // May be prepopulated if we know this in advance. @@ -113,6 +128,7 @@ impl Spec { self.state_root_memo.read().unwrap().as_ref().unwrap().clone() } + /// TODO [Gav Wood] Please document me pub fn genesis_header(&self) -> Header { Header { parent_hash: self.parent_hash.clone(), diff --git a/src/state.rs b/src/state.rs index 6ee0e8cd7..4b7e5af34 100644 --- a/src/state.rs +++ b/src/state.rs @@ -5,6 +5,7 @@ use pod_account::*; use pod_state::*; use state_diff::*; +/// TODO [Gav Wood] Please document me pub type ApplyResult = Result; /// Representation of the entire state of all accounts in the system. @@ -157,6 +158,7 @@ impl State { Ok(receipt) } + /// TODO [debris] Please document me pub fn revert(&mut self, backup: State) { self.cache = backup.cache; } diff --git a/src/state_diff.rs b/src/state_diff.rs index 1cc04b2d0..08fccf3ed 100644 --- a/src/state_diff.rs +++ b/src/state_diff.rs @@ -3,6 +3,7 @@ use pod_state::*; use account_diff::*; #[derive(Debug,Clone,PartialEq,Eq)] +/// TODO [Gav Wood] Please document me pub struct StateDiff (BTreeMap); impl StateDiff { diff --git a/src/substate.rs b/src/substate.rs index 9a1d6741e..5c4cde60c 100644 --- a/src/substate.rs +++ b/src/substate.rs @@ -25,6 +25,7 @@ impl Substate { } } + /// TODO [Gav Wood] Please document me pub fn accrue(&mut self, s: Substate) { self.suicides.extend(s.suicides.into_iter()); self.logs.extend(s.logs.into_iter()); diff --git a/src/sync/mod.rs b/src/sync/mod.rs index da91a6889..1ebc34d28 100644 --- a/src/sync/mod.rs +++ b/src/sync/mod.rs @@ -46,6 +46,7 @@ pub enum SyncMessage { BlockVerified, } +/// TODO [arkpar] Please document me pub type NetSyncMessage = NetworkIoMessage; /// Ethereum network protocol handler diff --git a/src/transaction.rs b/src/transaction.rs index 51bde4b86..47b8fa91f 100644 --- a/src/transaction.rs +++ b/src/transaction.rs @@ -4,8 +4,11 @@ use error::*; use evm::Schedule; #[derive(Debug,Clone)] +/// TODO [Gav Wood] Please document me pub enum Action { + /// TODO [Gav Wood] Please document me Create, + /// TODO [debris] Please document me Call(Address), } @@ -13,16 +16,25 @@ pub enum Action { /// or contract creation operation. #[derive(Debug,Clone)] pub struct Transaction { + /// TODO [debris] Please document me pub nonce: U256, + /// TODO [debris] Please document me pub gas_price: U256, + /// TODO [debris] Please document me pub gas: U256, + /// TODO [debris] Please document me pub action: Action, + /// TODO [debris] Please document me pub value: U256, + /// TODO [Gav Wood] Please document me pub data: Bytes, // signature + /// TODO [Gav Wood] Please document me pub v: u8, + /// TODO [Gav Wood] Please document me pub r: U256, + /// TODO [debris] Please document me pub s: U256, hash: RefCell>, @@ -30,6 +42,7 @@ pub struct Transaction { } impl Transaction { + /// TODO [Gav Wood] Please document me pub fn new() -> Self { Transaction { nonce: x!(0), diff --git a/util/src/bytes.rs b/util/src/bytes.rs index a954d8acd..a30581a1f 100644 --- a/util/src/bytes.rs +++ b/util/src/bytes.rs @@ -43,6 +43,7 @@ use std::ops::{Deref, DerefMut}; use uint::{Uint, U128, U256}; use hash::FixedHash; +/// TODO [Gav Wood] Please document me pub struct PrettySlice<'a> (&'a [u8]); impl<'a> fmt::Debug for PrettySlice<'a> { @@ -66,8 +67,11 @@ impl<'a> fmt::Display for PrettySlice<'a> { } } +/// TODO [Gav Wood] Please document me pub trait ToPretty { + /// TODO [Gav Wood] Please document me fn pretty(&self) -> PrettySlice; + /// TODO [Gav Wood] Please document me fn to_hex(&self) -> String { format!("{}", self.pretty()) } @@ -90,8 +94,11 @@ impl ToPretty for Bytes { } } +/// TODO [debris] Please document me pub enum BytesRef<'a> { + /// TODO [debris] Please document me Flexible(&'a mut Bytes), + /// TODO [debris] Please document me Fixed(&'a mut [u8]) } @@ -121,8 +128,11 @@ pub type Bytes = Vec; /// Slice of bytes to underlying memory pub trait BytesConvertable { // TODO: rename to as_slice + /// TODO [Gav Wood] Please document me fn bytes(&self) -> &[u8]; + /// TODO [Gav Wood] Please document me fn as_slice(&self) -> &[u8] { self.bytes() } + /// TODO [Gav Wood] Please document me fn to_bytes(&self) -> Bytes { self.as_slice().to_vec() } } @@ -160,8 +170,11 @@ fn bytes_convertable() { /// /// TODO: optimise some conversations pub trait ToBytes { + /// TODO [Gav Wood] Please document me fn to_bytes(&self) -> Vec; + /// TODO [Gav Wood] Please document me fn to_bytes_len(&self) -> usize { self.to_bytes().len() } + /// TODO [debris] Please document me fn first_byte(&self) -> Option { self.to_bytes().first().map(|&x| { x })} } @@ -257,7 +270,9 @@ impl ToBytes for T where T: FixedHash { /// Error returned when FromBytes conversation goes wrong #[derive(Debug, PartialEq, Eq)] pub enum FromBytesError { + /// TODO [debris] Please document me DataIsTooShort, + /// TODO [debris] Please document me DataIsTooLong } @@ -278,6 +293,7 @@ pub type FromBytesResult = Result; /// /// TODO: check size of bytes before conversation and return appropriate error pub trait FromBytes: Sized { + /// TODO [debris] Please document me fn from_bytes(bytes: &[u8]) -> FromBytesResult; } diff --git a/util/src/chainfilter.rs b/util/src/chainfilter.rs index 386664837..64f9e7d39 100644 --- a/util/src/chainfilter.rs +++ b/util/src/chainfilter.rs @@ -49,7 +49,9 @@ use sha3::*; /// index. Their `BloomIndex` can be created from block number and given level. #[derive(Eq, PartialEq, Hash, Clone, Debug)] pub struct BloomIndex { + /// TODO [debris] Please document me pub level: u8, + /// TODO [debris] Please document me pub index: usize, } diff --git a/util/src/common.rs b/util/src/common.rs index 3ec02ad9b..0f10a4e97 100644 --- a/util/src/common.rs +++ b/util/src/common.rs @@ -46,6 +46,7 @@ macro_rules! flushln { ($fmt:expr, $($arg:tt)*) => (flush!(concat!($fmt, "\n"), $($arg)*)); } +/// TODO [Gav Wood] Please document me pub fn flush(s: String) { ::std::io::stdout().write(s.as_bytes()).unwrap(); ::std::io::stdout().flush().unwrap(); diff --git a/util/src/crypto.rs b/util/src/crypto.rs index e9e440024..79a952a94 100644 --- a/util/src/crypto.rs +++ b/util/src/crypto.rs @@ -4,8 +4,11 @@ use uint::*; use secp256k1::{key, Secp256k1}; use rand::os::OsRng; +/// TODO [Gav Wood] Please document me pub type Secret = H256; +/// TODO [Gav Wood] Please document me pub type Public = H512; +/// TODO [Gav Wood] Please document me pub type Signature = H520; lazy_static! { @@ -33,11 +36,17 @@ impl Signature { } #[derive(Debug)] +/// TODO [arkpar] Please document me pub enum CryptoError { + /// TODO [arkpar] Please document me InvalidSecret, + /// TODO [arkpar] Please document me InvalidPublic, + /// TODO [arkpar] Please document me InvalidSignature, + /// TODO [arkpar] Please document me InvalidMessage, + /// TODO [arkpar] Please document me Io(::std::io::Error), } @@ -122,6 +131,7 @@ impl KeyPair { pub fn sign(&self, message: &H256) -> Result { ec::sign(&self.secret, message) } } +/// TODO [arkpar] Please document me pub mod ec { use hash::*; use uint::*; @@ -198,10 +208,12 @@ pub mod ec { } } +/// TODO [arkpar] Please document me pub mod ecdh { use crypto::*; use crypto::{self}; + /// TODO [arkpar] Please document me pub fn agree(secret: &Secret, public: &Public, ) -> Result { use secp256k1::*; let context = &crypto::SECP256K1; @@ -217,11 +229,13 @@ pub mod ecdh { } } +/// TODO [arkpar] Please document me pub mod ecies { use hash::*; use bytes::*; use crypto::*; + /// TODO [arkpar] Please document me pub fn encrypt(public: &Public, plain: &[u8]) -> Result { use ::rcrypto::digest::Digest; use ::rcrypto::sha2::Sha256; @@ -257,6 +271,7 @@ pub mod ecies { Ok(msg) } + /// TODO [arkpar] Please document me pub fn decrypt(secret: &Secret, encrypted: &[u8]) -> Result { use ::rcrypto::digest::Digest; use ::rcrypto::sha2::Sha256; @@ -322,17 +337,20 @@ pub mod ecies { } } +/// TODO [arkpar] Please document me pub mod aes { use ::rcrypto::blockmodes::*; use ::rcrypto::aessafe::*; use ::rcrypto::symmetriccipher::*; use ::rcrypto::buffer::*; + /// TODO [arkpar] Please document me pub fn encrypt(k: &[u8], iv: &[u8], plain: &[u8], dest: &mut [u8]) { let mut encryptor = CtrMode::new(AesSafe128Encryptor::new(k), iv.to_vec()); encryptor.encrypt(&mut RefReadBuffer::new(plain), &mut RefWriteBuffer::new(dest), true).expect("Invalid length or padding"); } + /// TODO [arkpar] Please document me pub fn decrypt(k: &[u8], iv: &[u8], encrypted: &[u8], dest: &mut [u8]) { let mut encryptor = CtrMode::new(AesSafe128Encryptor::new(k), iv.to_vec()); encryptor.decrypt(&mut RefReadBuffer::new(encrypted), &mut RefWriteBuffer::new(dest), true).expect("Invalid length or padding"); diff --git a/util/src/error.rs b/util/src/error.rs index d9687183d..0d13d329c 100644 --- a/util/src/error.rs +++ b/util/src/error.rs @@ -6,23 +6,36 @@ use rlp::DecoderError; use io; #[derive(Debug)] +/// TODO [Gav Wood] Please document me pub enum BaseDataError { + /// TODO [Gav Wood] Please document me NegativelyReferencedHash, } #[derive(Debug)] /// General error type which should be capable of representing all errors in ethcore. pub enum UtilError { + /// TODO [Gav Wood] Please document me Crypto(::crypto::CryptoError), + /// TODO [Gav Wood] Please document me StdIo(::std::io::Error), + /// TODO [Gav Wood] Please document me Io(io::IoError), + /// TODO [Gav Wood] Please document me AddressParse(::std::net::AddrParseError), + /// TODO [Gav Wood] Please document me AddressResolve(Option<::std::io::Error>), + /// TODO [Gav Wood] Please document me FromHex(FromHexError), + /// TODO [Gav Wood] Please document me BaseData(BaseDataError), + /// TODO [Gav Wood] Please document me Network(NetworkError), + /// TODO [Gav Wood] Please document me Decoder(DecoderError), + /// TODO [Gav Wood] Please document me SimpleString(String), + /// TODO [Gav Wood] Please document me BadSize, } diff --git a/util/src/from_json.rs b/util/src/from_json.rs index 71a3f50e3..1d95df691 100644 --- a/util/src/from_json.rs +++ b/util/src/from_json.rs @@ -7,6 +7,8 @@ macro_rules! xjson { } } +/// TODO [Gav Wood] Please document me pub trait FromJson { + /// TODO [Gav Wood] Please document me fn from_json(json: &Json) -> Self; } diff --git a/util/src/hash.rs b/util/src/hash.rs index bdd694cfc..252877a24 100644 --- a/util/src/hash.rs +++ b/util/src/hash.rs @@ -13,20 +13,33 @@ use uint::{Uint, U256}; /// /// Note: types implementing `FixedHash` must be also `BytesConvertable`. pub trait FixedHash: Sized + BytesConvertable + Populatable + FromStr + Default { + /// TODO [Gav Wood] Please document me fn new() -> Self; /// Synonym for `new()`. Prefer to new as it's more readable. fn zero() -> Self; + /// TODO [debris] Please document me fn random() -> Self; + /// TODO [debris] Please document me fn randomize(&mut self); + /// TODO [arkpar] Please document me fn size() -> usize; + /// TODO [arkpar] Please document me fn from_slice(src: &[u8]) -> Self; + /// TODO [arkpar] Please document me fn clone_from_slice(&mut self, src: &[u8]) -> usize; + /// TODO [Gav Wood] Please document me fn copy_to(&self, dest: &mut [u8]); + /// TODO [Gav Wood] Please document me fn shift_bloomed<'a, T>(&'a mut self, b: &T) -> &'a mut Self where T: FixedHash; + /// TODO [debris] Please document me fn with_bloomed(mut self, b: &T) -> Self where T: FixedHash { self.shift_bloomed(b); self } + /// TODO [Gav Wood] Please document me fn bloom_part(&self, m: usize) -> T where T: FixedHash; + /// TODO [debris] Please document me fn contains_bloomed(&self, b: &T) -> bool where T: FixedHash; + /// TODO [arkpar] Please document me fn contains<'a>(&'a self, b: &'a Self) -> bool; + /// TODO [debris] Please document me fn is_zero(&self) -> bool; } @@ -41,6 +54,7 @@ fn clean_0x(s: &str) -> &str { macro_rules! impl_hash { ($from: ident, $size: expr) => { #[derive(Eq)] + /// TODO [Gav Wood] Please document me pub struct $from (pub [u8; $size]); impl BytesConvertable for $from { @@ -396,10 +410,12 @@ macro_rules! impl_hash { } impl $from { + /// TODO [Gav Wood] Please document me pub fn hex(&self) -> String { format!("{:?}", self) } + /// TODO [Gav Wood] Please document me pub fn from_bloomed(b: &T) -> Self where T: FixedHash { b.bloom_part($size) } } @@ -503,21 +519,25 @@ impl<'_> From<&'_ Address> for H256 { } } +/// TODO [Gav Wood] Please document me pub fn h256_from_hex(s: &str) -> H256 { use std::str::FromStr; H256::from_str(s).unwrap() } +/// TODO [Gav Wood] Please document me pub fn h256_from_u64(n: u64) -> H256 { use uint::U256; H256::from(&U256::from(n)) } +/// TODO [Gav Wood] Please document me pub fn address_from_hex(s: &str) -> Address { use std::str::FromStr; Address::from_str(s).unwrap() } +/// TODO [Gav Wood] Please document me pub fn address_from_u64(n: u64) -> Address { let h256 = h256_from_u64(n); From::from(h256) diff --git a/util/src/io/mod.rs b/util/src/io/mod.rs index 23a8509cc..c59de0584 100644 --- a/util/src/io/mod.rs +++ b/util/src/io/mod.rs @@ -38,7 +38,9 @@ mod service; #[derive(Debug)] +/// TODO [arkpar] Please document me pub enum IoError { + /// TODO [arkpar] Please document me Mio(::std::io::Error), } @@ -66,10 +68,15 @@ pub trait IoHandler: Send where Message: Send + 'static { fn stream_writable<'s>(&'s mut self, _io: &mut IoContext<'s, Message>, _stream: StreamToken) {} } +/// TODO [arkpar] Please document me pub type TimerToken = service::TimerToken; +/// TODO [arkpar] Please document me pub type StreamToken = service::StreamToken; +/// TODO [arkpar] Please document me pub type IoContext<'s, M> = service::IoContext<'s, M>; +/// TODO [arkpar] Please document me pub type IoService = service::IoService; +/// TODO [arkpar] Please document me pub type IoChannel = service::IoChannel; //pub const USER_TOKEN_START: usize = service::USER_TOKEN; // TODO: ICE in rustc 1.7.0-nightly (49c382779 2016-01-12) diff --git a/util/src/json_aid.rs b/util/src/json_aid.rs index c716b8991..5974c5989 100644 --- a/util/src/json_aid.rs +++ b/util/src/json_aid.rs @@ -1,5 +1,6 @@ use common::*; +/// TODO [Gav Wood] Please document me pub fn clean(s: &str) -> &str { if s.len() >= 2 && &s[0..2] == "0x" { &s[2..] diff --git a/util/src/lib.rs b/util/src/lib.rs index 578a1d47a..d5acbc069 100644 --- a/util/src/lib.rs +++ b/util/src/lib.rs @@ -1,3 +1,4 @@ +#![warn(missing_docs)] #![feature(op_assign_traits)] #![feature(augmented_assignments)] #![feature(associated_consts)] @@ -54,17 +55,22 @@ extern crate secp256k1; extern crate arrayvec; extern crate elastic_array; +/// TODO [Gav Wood] Please document me pub mod standard; #[macro_use] +/// TODO [Gav Wood] Please document me pub mod from_json; #[macro_use] +/// TODO [Gav Wood] Please document me pub mod common; pub mod error; pub mod hash; pub mod uint; pub mod bytes; pub mod rlp; +/// TODO [Gav Wood] Please document me pub mod misc; +/// TODO [Gav Wood] Please document me pub mod json_aid; pub mod vector; pub mod sha3; @@ -72,16 +78,23 @@ pub mod hashdb; pub mod memorydb; pub mod overlaydb; pub mod journaldb; +/// TODO [Gav Wood] Please document me pub mod math; pub mod chainfilter; +/// TODO [Gav Wood] Please document me pub mod crypto; pub mod triehash; +/// TODO [Gav Wood] Please document me pub mod trie; pub mod nibbleslice; +/// TODO [Gav Wood] Please document me pub mod heapsizeof; pub mod squeeze; +/// TODO [Gav Wood] Please document me pub mod semantic_version; +/// TODO [Gav Wood] Please document me pub mod io; +/// TODO [Gav Wood] Please document me pub mod network; pub use common::*; diff --git a/util/src/memorydb.rs b/util/src/memorydb.rs index 6f2b2e603..f2935cceb 100644 --- a/util/src/memorydb.rs +++ b/util/src/memorydb.rs @@ -107,12 +107,14 @@ impl MemoryDB { self.data.get(key) } + /// TODO [Gav Wood] Please document me pub fn drain(&mut self) -> HashMap { let mut data = HashMap::new(); mem::swap(&mut self.data, &mut data); data } + /// TODO [Gav Wood] Please document me pub fn denote(&self, key: &H256, value: Bytes) -> &(Bytes, i32) { if self.raw(key) == None { unsafe { diff --git a/util/src/misc.rs b/util/src/misc.rs index d540ccf5b..316e78a11 100644 --- a/util/src/misc.rs +++ b/util/src/misc.rs @@ -3,9 +3,13 @@ use common::*; #[derive(Debug,Clone,PartialEq,Eq)] /// Diff type for specifying a change (or not). pub enum Diff where T: Eq { + /// TODO [Gav Wood] Please document me Same, + /// TODO [Gav Wood] Please document me Born(T), + /// TODO [Gav Wood] Please document me Changed(T, T), + /// TODO [Gav Wood] Please document me Died(T), } @@ -26,6 +30,8 @@ impl Diff where T: Eq { #[derive(PartialEq,Eq,Clone,Copy)] /// Boolean type for clean/dirty status. pub enum Filth { + /// TODO [Gav Wood] Please document me Clean, + /// TODO [Gav Wood] Please document me Dirty, } diff --git a/util/src/network/mod.rs b/util/src/network/mod.rs index a47e88927..2c9e71585 100644 --- a/util/src/network/mod.rs +++ b/util/src/network/mod.rs @@ -56,12 +56,18 @@ mod service; mod error; mod node; +/// TODO [arkpar] Please document me pub type PeerId = host::PeerId; +/// TODO [arkpar] Please document me pub type PacketId = host::PacketId; +/// TODO [arkpar] Please document me pub type NetworkContext<'s,'io, Message> = host::NetworkContext<'s, 'io, Message>; +/// TODO [arkpar] Please document me pub type NetworkService = service::NetworkService; +/// TODO [arkpar] Please document me pub type NetworkIoMessage = host::NetworkIoMessage; pub use network::host::NetworkIoMessage::User as UserMessage; +/// TODO [arkpar] Please document me pub type NetworkError = error::NetworkError; use io::*; diff --git a/util/src/nibbleslice.rs b/util/src/nibbleslice.rs index b9028dff3..c0d076440 100644 --- a/util/src/nibbleslice.rs +++ b/util/src/nibbleslice.rs @@ -34,6 +34,7 @@ pub struct NibbleSlice<'a> { offset_encode_suffix: usize, } +/// TODO [Gav Wood] Please document me pub struct NibbleSliceIterator<'a> { p: &'a NibbleSlice<'a>, i: usize, @@ -76,6 +77,7 @@ impl<'a, 'view> NibbleSlice<'a> where 'a: 'view { (r, a.len() + b.len()) }*/ + /// TODO [Gav Wood] Please document me pub fn iter(&'a self) -> NibbleSliceIterator<'a> { NibbleSliceIterator { p: self, i: 0 } } @@ -130,6 +132,7 @@ impl<'a, 'view> NibbleSlice<'a> where 'a: 'view { i } + /// TODO [Gav Wood] Please document me pub fn encoded(&self, is_leaf: bool) -> Bytes { let l = self.len(); let mut r = Bytes::with_capacity(l / 2 + 1); @@ -142,6 +145,7 @@ impl<'a, 'view> NibbleSlice<'a> where 'a: 'view { r } + /// TODO [Gav Wood] Please document me pub fn encoded_leftmost(&self, n: usize, is_leaf: bool) -> Bytes { let l = min(self.len(), n); let mut r = Bytes::with_capacity(l / 2 + 1); diff --git a/util/src/rlp/mod.rs b/util/src/rlp/mod.rs index fc0a4d288..f6acdf180 100644 --- a/util/src/rlp/mod.rs +++ b/util/src/rlp/mod.rs @@ -30,10 +30,15 @@ //! * You want to get view onto rlp-slice. //! * You don't want to decode whole rlp at once. +/// TODO [Gav Wood] Please document me pub mod rlptraits; +/// TODO [Gav Wood] Please document me pub mod rlperrors; +/// TODO [debris] Please document me pub mod rlpin; +/// TODO [debris] Please document me pub mod untrusted_rlp; +/// TODO [debris] Please document me pub mod rlpstream; #[cfg(test)] @@ -46,9 +51,13 @@ pub use self::rlpin::{Rlp, RlpIterator}; pub use self::rlpstream::{RlpStream,RlpStandard}; use super::hash::H256; +/// TODO [arkpar] Please document me pub const NULL_RLP: [u8; 1] = [0x80; 1]; +/// TODO [Gav Wood] Please document me pub const EMPTY_LIST_RLP: [u8; 1] = [0xC0; 1]; +/// TODO [arkpar] Please document me pub const SHA3_NULL_RLP: H256 = H256( [0x56, 0xe8, 0x1f, 0x17, 0x1b, 0xcc, 0x55, 0xa6, 0xff, 0x83, 0x45, 0xe6, 0x92, 0xc0, 0xf8, 0x6e, 0x5b, 0x48, 0xe0, 0x1b, 0x99, 0x6c, 0xad, 0xc0, 0x01, 0x62, 0x2f, 0xb5, 0xe3, 0x63, 0xb4, 0x21] ); +/// TODO [debris] Please document me pub const SHA3_EMPTY_LIST_RLP: H256 = H256( [0x1d, 0xcc, 0x4d, 0xe8, 0xde, 0xc7, 0x5d, 0x7a, 0xab, 0x85, 0xb5, 0x67, 0xb6, 0xcc, 0xd4, 0x1a, 0xd3, 0x12, 0x45, 0x1b, 0x94, 0x8a, 0x74, 0x13, 0xf0, 0xa1, 0x42, 0xfd, 0x40, 0xd4, 0x93, 0x47] ); /// Shortcut function to decode trusted rlp diff --git a/util/src/rlp/rlperrors.rs b/util/src/rlp/rlperrors.rs index 9ea470abf..97adbced1 100644 --- a/util/src/rlp/rlperrors.rs +++ b/util/src/rlp/rlperrors.rs @@ -3,14 +3,23 @@ use std::error::Error as StdError; use bytes::FromBytesError; #[derive(Debug, PartialEq, Eq)] +/// TODO [debris] Please document me pub enum DecoderError { + /// TODO [debris] Please document me FromBytesError(FromBytesError), + /// TODO [debris] Please document me RlpIsTooShort, + /// TODO [debris] Please document me RlpExpectedToBeList, + /// TODO [Gav Wood] Please document me RlpExpectedToBeData, + /// TODO [Gav Wood] Please document me RlpIncorrectListLen, + /// TODO [Gav Wood] Please document me RlpDataLenWithZeroPrefix, + /// TODO [Gav Wood] Please document me RlpListLenWithZeroPrefix, + /// TODO [debris] Please document me RlpInvalidIndirection, } diff --git a/util/src/rlp/rlpin.rs b/util/src/rlp/rlpin.rs index 159130750..5cecce44f 100644 --- a/util/src/rlp/rlpin.rs +++ b/util/src/rlp/rlpin.rs @@ -103,10 +103,12 @@ impl <'a, 'view> Rlp<'a> where 'a: 'view { res.unwrap_or_else(|_| panic!()) } + /// TODO [debris] Please document me pub fn as_val(&self) -> T where T: Decodable { Self::view_as_val(self) } + /// TODO [debris] Please document me pub fn val_at(&self, index: usize) -> T where T: Decodable { Self::view_as_val(&self.at(index)) } diff --git a/util/src/rlp/rlpstream.rs b/util/src/rlp/rlpstream.rs index 36ac1ba33..ac22736fc 100644 --- a/util/src/rlp/rlpstream.rs +++ b/util/src/rlp/rlpstream.rs @@ -223,15 +223,19 @@ impl Encoder for BasicEncoder { } } +/// TODO [Gav Wood] Please document me pub trait RlpStandard { + /// TODO [Gav Wood] Please document me fn rlp_append(&self, s: &mut RlpStream); + /// TODO [Gav Wood] Please document me fn rlp_bytes(&self) -> Bytes { let mut s = RlpStream::new(); self.rlp_append(&mut s); s.out() } + /// TODO [Gav Wood] Please document me fn rlp_sha3(&self) -> H256 { self.rlp_bytes().sha3() } } diff --git a/util/src/rlp/rlptraits.rs b/util/src/rlp/rlptraits.rs index 162f990fe..d6ef16932 100644 --- a/util/src/rlp/rlptraits.rs +++ b/util/src/rlp/rlptraits.rs @@ -1,23 +1,36 @@ use rlp::{DecoderError, UntrustedRlp}; +/// TODO [debris] Please document me pub trait Decoder: Sized { + /// TODO [debris] Please document me fn read_value(&self, f: F) -> Result where F: FnOnce(&[u8]) -> Result; + /// TODO [arkpar] Please document me fn as_list(&self) -> Result, DecoderError>; + /// TODO [Gav Wood] Please document me fn as_rlp(&self) -> &UntrustedRlp; + /// TODO [debris] Please document me fn as_raw(&self) -> &[u8]; } +/// TODO [debris] Please document me pub trait Decodable: Sized { + /// TODO [debris] Please document me fn decode(decoder: &D) -> Result where D: Decoder; } +/// TODO [debris] Please document me pub trait View<'a, 'view>: Sized { + /// TODO [debris] Please document me type Prototype; + /// TODO [debris] Please document me type PayloadInfo; + /// TODO [debris] Please document me type Data; + /// TODO [debris] Please document me type Item; + /// TODO [debris] Please document me type Iter; /// Creates a new instance of `Rlp` reader @@ -41,8 +54,10 @@ pub trait View<'a, 'view>: Sized { /// Get the prototype of the RLP. fn prototype(&self) -> Self::Prototype; + /// TODO [debris] Please document me fn payload_info(&self) -> Self::PayloadInfo; + /// TODO [debris] Please document me fn data(&'view self) -> Self::Data; /// Returns number of RLP items. @@ -179,21 +194,30 @@ pub trait View<'a, 'view>: Sized { /// ``` fn iter(&'view self) -> Self::Iter; + /// TODO [debris] Please document me fn as_val(&self) -> Result where T: Decodable; + /// TODO [debris] Please document me fn val_at(&self, index: usize) -> Result where T: Decodable; } +/// TODO [debris] Please document me pub trait Encoder { + /// TODO [debris] Please document me fn emit_value(&mut self, bytes: &[u8]) -> (); + /// TODO [Gav Wood] Please document me fn emit_list(&mut self, f: F) -> () where F: FnOnce(&mut Self) -> (); + /// TODO [debris] Please document me fn emit_raw(&mut self, bytes: &[u8]) -> (); } +/// TODO [debris] Please document me pub trait Encodable { + /// TODO [debris] Please document me fn encode(&self, encoder: &mut E) -> () where E: Encoder; } +/// TODO [debris] Please document me pub trait Stream: Sized { /// Initializes instance of empty `Stream`. @@ -284,6 +308,7 @@ pub trait Stream: Sized { /// } fn is_finished(&self) -> bool; + /// TODO [debris] Please document me fn as_raw(&self) -> &[u8]; /// Streams out encoded bytes. diff --git a/util/src/rlp/untrusted_rlp.rs b/util/src/rlp/untrusted_rlp.rs index 9c9246115..768d058c1 100644 --- a/util/src/rlp/untrusted_rlp.rs +++ b/util/src/rlp/untrusted_rlp.rs @@ -21,15 +21,21 @@ impl OffsetCache { } #[derive(Debug)] +/// TODO [debris] Please document me pub enum Prototype { + /// TODO [debris] Please document me Null, + /// TODO [debris] Please document me Data(usize), + /// TODO [debris] Please document me List(usize), } /// Stores basic information about item pub struct PayloadInfo { + /// TODO [debris] Please document me pub header_len: usize, + /// TODO [debris] Please document me pub value_len: usize, } diff --git a/util/src/sha3.rs b/util/src/sha3.rs index a33ac61f7..115a408de 100644 --- a/util/src/sha3.rs +++ b/util/src/sha3.rs @@ -6,6 +6,7 @@ use bytes::{BytesConvertable, Populatable}; use hash::{H256, FixedHash}; use self::sha3_ext::*; +/// TODO [Gav Wood] Please document me pub const SHA3_EMPTY: H256 = H256( [0xc5, 0xd2, 0x46, 0x01, 0x86, 0xf7, 0x23, 0x3c, 0x92, 0x7e, 0x7d, 0xb2, 0xdc, 0xc7, 0x03, 0xc0, 0xe5, 0x00, 0xb6, 0x53, 0xca, 0x82, 0x27, 0x3b, 0x7b, 0xfa, 0xd8, 0x04, 0x5d, 0x85, 0xa4, 0x70] ); diff --git a/util/src/squeeze.rs b/util/src/squeeze.rs index f83c5cee9..3fb4a81f9 100644 --- a/util/src/squeeze.rs +++ b/util/src/squeeze.rs @@ -36,6 +36,7 @@ use heapsize::HeapSizeOf; /// Should be used to squeeze collections to certain size in bytes pub trait Squeeze { + /// TODO [debris] Please document me fn squeeze(&mut self, size: usize); } diff --git a/util/src/trie/mod.rs b/util/src/trie/mod.rs index 1b5919bd4..ce796bd15 100644 --- a/util/src/trie/mod.rs +++ b/util/src/trie/mod.rs @@ -1,10 +1,17 @@ +/// TODO [Gav Wood] Please document me pub mod trietraits; pub mod standardmap; +/// TODO [Gav Wood] Please document me pub mod journal; +/// TODO [Gav Wood] Please document me pub mod node; +/// TODO [Gav Wood] Please document me pub mod triedb; +/// TODO [Gav Wood] Please document me pub mod triedbmut; +/// TODO [Gav Wood] Please document me pub mod sectriedb; +/// TODO [Gav Wood] Please document me pub mod sectriedbmut; pub use self::trietraits::*; diff --git a/util/src/trie/node.rs b/util/src/trie/node.rs index b10b0e05e..dad5830b2 100644 --- a/util/src/trie/node.rs +++ b/util/src/trie/node.rs @@ -7,9 +7,13 @@ use super::journal::*; /// Type of node in the trie and essential information thereof. #[derive(Clone, Eq, PartialEq, Debug)] pub enum Node<'a> { + /// TODO [Gav Wood] Please document me Empty, + /// TODO [Gav Wood] Please document me Leaf(NibbleSlice<'a>, &'a[u8]), + /// TODO [Gav Wood] Please document me Extension(NibbleSlice<'a>, &'a[u8]), + /// TODO [Gav Wood] Please document me Branch([&'a[u8]; 16], Option<&'a [u8]>) } diff --git a/util/src/trie/standardmap.rs b/util/src/trie/standardmap.rs index b1ca03d22..0e65849cc 100644 --- a/util/src/trie/standardmap.rs +++ b/util/src/trie/standardmap.rs @@ -7,9 +7,13 @@ use hash::*; /// Alphabet to use when creating words for insertion into tries. pub enum Alphabet { + /// TODO [Gav Wood] Please document me All, + /// TODO [Gav Wood] Please document me Low, + /// TODO [Gav Wood] Please document me Mid, + /// TODO [Gav Wood] Please document me Custom(Bytes), } diff --git a/util/src/trie/triedb.rs b/util/src/trie/triedb.rs index 612bcdf7a..7179c395e 100644 --- a/util/src/trie/triedb.rs +++ b/util/src/trie/triedb.rs @@ -34,6 +34,7 @@ use super::node::*; pub struct TrieDB<'db> { db: &'db HashDB, root: &'db H256, + /// TODO [Gav Wood] Please document me pub hash_count: usize, } diff --git a/util/src/trie/triedbmut.rs b/util/src/trie/triedbmut.rs index f52c9bc1e..48749bf0d 100644 --- a/util/src/trie/triedbmut.rs +++ b/util/src/trie/triedbmut.rs @@ -40,6 +40,7 @@ use super::trietraits::*; pub struct TrieDBMut<'db> { db: &'db mut HashDB, root: &'db mut H256, + /// TODO [Gav Wood] Please document me pub hash_count: usize, } diff --git a/util/src/uint.rs b/util/src/uint.rs index bd51aad40..ab136d7c6 100644 --- a/util/src/uint.rs +++ b/util/src/uint.rs @@ -58,15 +58,20 @@ macro_rules! panic_on_overflow { } } +/// TODO [Gav Wood] Please document me pub trait Uint: Sized + Default + FromStr + From + FromJson + fmt::Debug + fmt::Display + PartialOrd + Ord + PartialEq + Eq + Hash { /// Size of this type. const SIZE: usize; + /// TODO [Gav Wood] Please document me fn zero() -> Self; + /// TODO [Gav Wood] Please document me fn one() -> Self; + /// TODO [Gav Wood] Please document me type FromDecStrErr; + /// TODO [Gav Wood] Please document me fn from_dec_str(value: &str) -> Result; /// Conversion to u32 @@ -98,18 +103,25 @@ pub trait Uint: Sized + Default + FromStr + From + FromJson + fmt::Debug + fn overflowing_pow(self, other: Self) -> (Self, bool); + /// TODO [debris] Please document me fn overflowing_add(self, other: Self) -> (Self, bool); + /// TODO [debris] Please document me fn overflowing_sub(self, other: Self) -> (Self, bool); + /// TODO [debris] Please document me fn overflowing_mul(self, other: Self) -> (Self, bool); + /// TODO [debris] Please document me fn overflowing_div(self, other: Self) -> (Self, bool); + /// TODO [debris] Please document me fn overflowing_rem(self, other: Self) -> (Self, bool); + /// TODO [debris] Please document me fn overflowing_neg(self) -> (Self, bool); + /// TODO [Gav Wood] Please document me fn overflowing_shl(self, shift: u32) -> (Self, bool); } @@ -914,8 +926,11 @@ impl From for u32 { } } +/// TODO [Gav Wood] Please document me pub const ZERO_U256: U256 = U256([0x00u64; 4]); +/// TODO [Gav Wood] Please document me pub const ONE_U256: U256 = U256([0x01u64, 0x00u64, 0x00u64, 0x00u64]); +/// TODO [Gav Wood] Please document me pub const BAD_U256: U256 = U256([0xffffffffffffffffu64; 4]); #[cfg(test)] diff --git a/util/src/vector.rs b/util/src/vector.rs index 552e285cf..94b5ee70c 100644 --- a/util/src/vector.rs +++ b/util/src/vector.rs @@ -2,7 +2,9 @@ use std::ptr; +/// TODO [debris] Please document me pub trait InsertSlice { + /// TODO [debris] Please document me fn insert_slice(&mut self, index: usize, elements: &[T]); } @@ -47,6 +49,7 @@ impl InsertSlice for Vec { /// } /// ``` pub trait SharedPrefix { + /// TODO [debris] Please document me fn shared_prefix_len(&self, elem: &[T]) -> usize; }