From c531150f4409ec61c250b40313d3609c204ee0a2 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Wed, 3 Feb 2016 13:20:32 +0100 Subject: [PATCH] More documentation. --- ethcore/src/ethereum/mod.rs | 4 +-- ethcore/src/extras.rs | 4 +-- ethcore/src/header.rs | 46 ++++++++++++++++----------------- ethcore/src/json_tests/chain.rs | 6 ++--- ethcore/src/json_tests/state.rs | 8 +++--- ethcore/src/log_entry.rs | 8 +++--- ethcore/src/pod_account.rs | 11 ++++---- ethcore/src/pod_state.rs | 2 +- ethcore/src/receipt.rs | 10 +++---- ethcore/src/spec.rs | 41 ++++++++++++++--------------- ethcore/src/state.rs | 2 +- ethcore/src/state_diff.rs | 3 ++- ethcore/src/substate.rs | 2 +- ethcore/src/transaction.rs | 8 +++--- util/src/bytes.rs | 14 +++++----- util/src/common.rs | 2 +- util/src/trie/triedbmut.rs | 2 +- 17 files changed, 87 insertions(+), 86 deletions(-) diff --git a/ethcore/src/ethereum/mod.rs b/ethcore/src/ethereum/mod.rs index c32fc40c6..ec6cfe103 100644 --- a/ethcore/src/ethereum/mod.rs +++ b/ethcore/src/ethereum/mod.rs @@ -3,9 +3,9 @@ //! Contains all Ethereum network specific stuff, such as denominations and //! consensus specifications. -/// TODO [Gav Wood] Please document me +/// Export the ethash module. pub mod ethash; -/// TODO [Gav Wood] Please document me +/// Export the denominations module. pub mod denominations; pub use self::ethash::*; diff --git a/ethcore/src/extras.rs b/ethcore/src/extras.rs index be5121a2d..f3f3208ad 100644 --- a/ethcore/src/extras.rs +++ b/ethcore/src/extras.rs @@ -68,9 +68,9 @@ impl ExtrasReadable for DB { /// Implementations should convert arbitrary type to database key slice pub trait ExtrasSliceConvertable { - /// TODO [Gav Wood] Please document me + /// Convert self, with `i` (the index), to a 264-bit extras DB key. fn to_extras_slice(&self, i: ExtrasIndex) -> H264; - /// TODO [debris] Please document me + /// Interpret self as a 256-bit hash, if natively `H256`. fn as_h256(&self) -> Option<&H256> { None } } diff --git a/ethcore/src/header.rs b/ethcore/src/header.rs index 69dba5ec8..b188a6bcf 100644 --- a/ethcore/src/header.rs +++ b/ethcore/src/header.rs @@ -48,9 +48,9 @@ pub struct Header { /// Block seal. pub seal: Vec, - /// TODO [arkpar] Please document me + /// The memoized hash of the RLP representation *including* the seal fields. pub hash: RefCell>, - /// TODO [Gav Wood] Please document me + /// The memoized hash of the RLP representation *without* the seal fields. pub bare_hash: RefCell>, } @@ -86,50 +86,50 @@ impl Header { Self::default() } - /// TODO [Gav Wood] Please document me + /// Get the number field of the header. pub fn number(&self) -> BlockNumber { self.number } - /// TODO [Gav Wood] Please document me + /// Get the timestamp field of the header. pub fn timestamp(&self) -> u64 { self.timestamp } - /// TODO [Gav Wood] Please document me + /// Get the author field of the header. pub fn author(&self) -> &Address { &self.author } - /// TODO [Gav Wood] Please document me + /// Get the extra data field of the header. pub fn extra_data(&self) -> &Bytes { &self.extra_data } - /// TODO [Gav Wood] Please document me + /// Get the state root field of the header. pub fn state_root(&self) -> &H256 { &self.state_root } - /// TODO [Gav Wood] Please document me + /// Get the receipts root field of the header. pub fn receipts_root(&self) -> &H256 { &self.receipts_root } - /// TODO [Gav Wood] Please document me + /// Get the gas limit field of the header. pub fn gas_limit(&self) -> &U256 { &self.gas_limit } - /// TODO [Gav Wood] Please document me + /// Get the difficulty field of the header. pub fn difficulty(&self) -> &U256 { &self.difficulty } - /// TODO [Gav Wood] Please document me + /// Get the seal field of the header. pub fn seal(&self) -> &Vec { &self.seal } // TODO: seal_at, set_seal_at &c. - /// TODO [Gav Wood] Please document me + /// Set the number field of the header. pub fn set_number(&mut self, a: BlockNumber) { self.number = a; self.note_dirty(); } - /// TODO [Gav Wood] Please document me + /// Set the timestamp field of the header. pub fn set_timestamp(&mut self, a: u64) { self.timestamp = a; self.note_dirty(); } - /// TODO [Gav Wood] Please document me + /// Set the timestamp field of the header to the current time. 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 + /// Set the author field of the header. pub fn set_author(&mut self, a: Address) { if a != self.author { self.author = a; self.note_dirty(); } } - /// TODO [Gav Wood] Please document me + /// Set the extra data field of the header. 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 + /// Set the gas used field of the header. pub fn set_gas_used(&mut self, a: U256) { self.gas_used = a; self.note_dirty(); } - /// TODO [Gav Wood] Please document me + /// Set the gas limit field of the header. pub fn set_gas_limit(&mut self, a: U256) { self.gas_limit = a; self.note_dirty(); } - /// TODO [Gav Wood] Please document me + /// Set the difficulty field of the header. pub fn set_difficulty(&mut self, a: U256) { self.difficulty = a; self.note_dirty(); } - /// TODO [Gav Wood] Please document me + /// Set the seal field of the header. pub fn set_seal(&mut self, a: Vec) { self.seal = a; self.note_dirty(); } /// Get the hash of this header (sha3 of the RLP). @@ -163,7 +163,7 @@ impl Header { } // TODO: make these functions traity - /// TODO [Gav Wood] Please document me + /// Place this header into an RLP stream `s`, optionally `with_seal`. pub fn stream_rlp(&self, s: &mut RlpStream, with_seal: Seal) { s.begin_list(13 + match with_seal { Seal::With => self.seal.len(), _ => 0 }); s.append(&self.parent_hash); @@ -186,14 +186,14 @@ impl Header { } } - /// TODO [Gav Wood] Please document me + /// Get the RLP of this header, optionally `with_seal`. 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 + /// Get the SHA3 (Keccak) of this header, optionally `with_seal`. pub fn rlp_sha3(&self, with_seal: Seal) -> H256 { self.rlp(with_seal).sha3() } } diff --git a/ethcore/src/json_tests/chain.rs b/ethcore/src/json_tests/chain.rs index 19e792f52..6ee7e9f9e 100644 --- a/ethcore/src/json_tests/chain.rs +++ b/ethcore/src/json_tests/chain.rs @@ -15,12 +15,12 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec { { let mut fail_unless = |cond: bool| if !cond && !fail { failed.push(name.clone()); - flush(format!("FAIL\n")); + flushln!("FAIL"); fail = true; true } else {false}; - flush(format!(" - {}...", name)); + flush!(" - {}...", name); let blocks: Vec<(Bytes, bool)> = test["blocks"].as_array().unwrap().iter().map(|e| (xjson!(&e["rlp"]), e.find("blockHeader").is_some())).collect(); let mut spec = match era { @@ -50,7 +50,7 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec { } } if !fail { - flush(format!("ok\n")); + flushln!("ok"); } } println!("!!! {:?} tests from failed.", failed.len()); diff --git a/ethcore/src/json_tests/state.rs b/ethcore/src/json_tests/state.rs index 3fb43c132..fa8da9329 100644 --- a/ethcore/src/json_tests/state.rs +++ b/ethcore/src/json_tests/state.rs @@ -19,19 +19,19 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec { ChainEra::Homestead => ethereum::new_homestead_test(), }.to_engine().unwrap(); - flush(format!("\n")); + flushln!(""); for (name, test) in json.as_object().unwrap() { let mut fail = false; { let mut fail_unless = |cond: bool| if !cond && !fail { failed.push(name.clone()); - flush(format!("FAIL\n")); + flushln!("FAIL"); fail = true; true } else {false}; - flush(format!(" - {}...", name)); + flush!(" - {}...", name); let t = Transaction::from_json(&test["transaction"]); let env = EnvInfo::from_json(&test["env"]); @@ -73,7 +73,7 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec { } } if !fail { - flush(format!("ok\n")); + flushln!("ok"); } // TODO: Add extra APIs for output //if fail_unless(out == r.) diff --git a/ethcore/src/log_entry.rs b/ethcore/src/log_entry.rs index 165c6985e..46faad797 100644 --- a/ethcore/src/log_entry.rs +++ b/ethcore/src/log_entry.rs @@ -1,14 +1,14 @@ use util::*; use basic_types::LogBloom; -/// A single log's entry. +/// A record of execution for a `LOG` operation. #[derive(Default, Debug, Clone, PartialEq, Eq)] pub struct LogEntry { - /// TODO [Gav Wood] Please document me + /// The address of the contract executing at the point of the `LOG` operation. pub address: Address, - /// TODO [Gav Wood] Please document me + /// The topics associated with the `LOG` operation. pub topics: Vec, - /// TODO [Gav Wood] Please document me + /// The data associated with the `LOG` operation. pub data: Bytes, } diff --git a/ethcore/src/pod_account.rs b/ethcore/src/pod_account.rs index 76127b89a..7bc886617 100644 --- a/ethcore/src/pod_account.rs +++ b/ethcore/src/pod_account.rs @@ -2,15 +2,16 @@ use util::*; use account::*; #[derive(Debug,Clone,PartialEq,Eq)] -/// Genesis account data. Does not have a DB overlay cache. +/// An account, expressed as Plain-Old-Data (hence the name). +/// Does not have a DB overlay cache, code hash or anything like that. pub struct PodAccount { - /// TODO [Gav Wood] Please document me + /// The balance of the account. pub balance: U256, - /// TODO [Gav Wood] Please document me + /// The nonce of the account. pub nonce: U256, - /// TODO [Gav Wood] Please document me + /// The code of the account. pub code: Bytes, - /// TODO [Gav Wood] Please document me + /// The storage of the account. pub storage: BTreeMap, } diff --git a/ethcore/src/pod_state.rs b/ethcore/src/pod_state.rs index 22969f36b..b373171ad 100644 --- a/ethcore/src/pod_state.rs +++ b/ethcore/src/pod_state.rs @@ -2,7 +2,7 @@ use util::*; use pod_account::*; #[derive(Debug,Clone,PartialEq,Eq,Default)] -/// TODO [Gav Wood] Please document me +/// State of all accounts in the system expressed in Plain Old Data. pub struct PodState (BTreeMap); impl PodState { diff --git a/ethcore/src/receipt.rs b/ethcore/src/receipt.rs index b12cbab23..43f674aa9 100644 --- a/ethcore/src/receipt.rs +++ b/ethcore/src/receipt.rs @@ -5,18 +5,18 @@ use log_entry::LogEntry; /// Information describing execution of a transaction. #[derive(Default, Debug, Clone)] pub struct Receipt { - /// TODO [Gav Wood] Please document me + /// The state root after executing the transaction. pub state_root: H256, - /// TODO [Gav Wood] Please document me + /// The total gas used in the block following execution of the transaction. pub gas_used: U256, - /// TODO [Gav Wood] Please document me + /// The OR-wide combination of all logs' blooms for this transaction. pub log_bloom: LogBloom, - /// TODO [Gav Wood] Please document me + /// The logs stemming from this transaction. pub logs: Vec, } impl Receipt { - /// TODO [Gav Wood] Please document me + /// Create a new receipt. pub fn new(state_root: H256, gas_used: U256, logs: Vec) -> Receipt { Receipt { state_root: state_root, diff --git a/ethcore/src/spec.rs b/ethcore/src/spec.rs index 7cb251096..50bbbb633 100644 --- a/ethcore/src/spec.rs +++ b/ethcore/src/spec.rs @@ -34,53 +34,50 @@ fn json_to_rlp_map(json: &Json) -> HashMap { /// chain and those to be interpreted by the active chain engine. #[derive(Debug)] pub struct Spec { - // User friendly spec name - /// TODO [Gav Wood] Please document me + /// User friendly spec name pub name: String, - // What engine are we using for this? - /// TODO [Gav Wood] Please document me + /// What engine are we using for this? pub engine_name: String, /// Known nodes on the network in enode format. pub nodes: Vec, - // Parameters concerning operation of the specific engine we're using. - // Name -> RLP-encoded value - /// TODO [Gav Wood] Please document me + /// Parameters concerning operation of the specific engine we're using. + /// Maps the parameter name to an RLP-encoded value. 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 + /// Builtin-contracts we would like to see in the chain. + /// (In principle these are just hints for the engine since that has the last word on them.) pub builtins: BTreeMap, - // Genesis params. - /// TODO [Gav Wood] Please document me + /// The genesis block's parent hash field. pub parent_hash: H256, - /// TODO [Gav Wood] Please document me + /// The genesis block's author field. pub author: Address, - /// TODO [Gav Wood] Please document me + /// The genesis block's difficulty field. pub difficulty: U256, - /// TODO [Gav Wood] Please document me + /// The genesis block's gas limit field. pub gas_limit: U256, - /// TODO [Gav Wood] Please document me + /// The genesis block's gas used field. pub gas_used: U256, - /// TODO [Gav Wood] Please document me + /// The genesis block's timestamp field. pub timestamp: u64, /// Transactions root of the genesis block. Should be SHA3_NULL_RLP. pub transactions_root: H256, /// Receipts root of the genesis block. Should be SHA3_NULL_RLP. pub receipts_root: H256, - /// TODO [arkpar] Please document me + /// The genesis block's extra data field. pub extra_data: Bytes, - /// TODO [Gav Wood] Please document me - genesis_state: PodState, - /// TODO [Gav Wood] Please document me + /// The number of seal fields in the genesis block. pub seal_fields: usize, - /// TODO [Gav Wood] Please document me + /// Each seal field, expressed as RLP, concatenated. pub seal_rlp: Bytes, // May be prepopulated if we know this in advance. state_root_memo: RwLock>, + + // Genesis state as plain old data. + genesis_state: PodState, } #[allow(wrong_self_convention)] // because to_engine(self) should be to_engine(&self) @@ -106,7 +103,7 @@ impl Spec { /// Get the known knodes of the network in enode format. pub fn nodes(&self) -> &Vec { &self.nodes } - /// TODO [Gav Wood] Please document me + /// Get the header of the genesis block. pub fn genesis_header(&self) -> Header { Header { parent_hash: self.parent_hash.clone(), diff --git a/ethcore/src/state.rs b/ethcore/src/state.rs index fb336f3bb..3c12804b9 100644 --- a/ethcore/src/state.rs +++ b/ethcore/src/state.rs @@ -5,7 +5,7 @@ use pod_account::*; use pod_state::PodState; //use state_diff::*; // TODO: uncomment once to_pod() works correctly. -/// TODO [Gav Wood] Please document me +/// Result type for the execution ("application") of a transaction. pub type ApplyResult = Result; /// Representation of the entire state of all accounts in the system. diff --git a/ethcore/src/state_diff.rs b/ethcore/src/state_diff.rs index 12e2d76ca..1caa62ef1 100644 --- a/ethcore/src/state_diff.rs +++ b/ethcore/src/state_diff.rs @@ -3,7 +3,8 @@ use pod_state::*; use account_diff::*; #[derive(Debug,Clone,PartialEq,Eq)] -/// TODO [Gav Wood] Please document me +/// Expression for the delta between two system states. Encoded the +/// delta of every altered account. pub struct StateDiff (BTreeMap); impl StateDiff { diff --git a/ethcore/src/substate.rs b/ethcore/src/substate.rs index 182cef93b..a5c353351 100644 --- a/ethcore/src/substate.rs +++ b/ethcore/src/substate.rs @@ -26,7 +26,7 @@ impl Substate { } } - /// TODO [Gav Wood] Please document me + /// Merge secondary substate `s` into self, accruing each element correspondingly. pub fn accrue(&mut self, s: Substate) { self.suicides.extend(s.suicides.into_iter()); self.logs.extend(s.logs.into_iter()); diff --git a/ethcore/src/transaction.rs b/ethcore/src/transaction.rs index d71506672..bc777d7ae 100644 --- a/ethcore/src/transaction.rs +++ b/ethcore/src/transaction.rs @@ -36,11 +36,11 @@ pub struct Transaction { pub data: Bytes, // signature - /// TODO [Gav Wood] Please document me + /// The V field of the signature, either 27 or 28; helps describe the point on the curve. pub v: u8, - /// TODO [Gav Wood] Please document me + /// The R field of the signature; helps describe the point on the curve. pub r: U256, - /// TODO [debris] Please document me + /// The S field of the signature; helps describe the point on the curve. pub s: U256, hash: RefCell>, @@ -48,7 +48,7 @@ pub struct Transaction { } impl Transaction { - /// TODO [Gav Wood] Please document me + /// Create a new transaction. #[cfg(test)] pub fn new() -> Self { Transaction { diff --git a/util/src/bytes.rs b/util/src/bytes.rs index 050c07a66..f4937cafc 100644 --- a/util/src/bytes.rs +++ b/util/src/bytes.rs @@ -83,11 +83,12 @@ impl<'a> fmt::Display for PrettySlice<'a> { } } -/// TODO [Gav Wood] Please document me +/// Trait to allow a type to be pretty-printed in `format!`, where unoverridable +/// defaults cannot otherwise be avoided. pub trait ToPretty { - /// TODO [Gav Wood] Please document me + /// Convert a type into a derivative form in order to make `format!` print it prettily. fn pretty(&self) -> PrettySlice; - /// TODO [Gav Wood] Please document me + /// Express the object as a hex string. fn to_hex(&self) -> String { format!("{}", self.pretty()) } @@ -144,11 +145,12 @@ pub type Bytes = Vec; /// Slice of bytes to underlying memory pub trait BytesConvertable { // TODO: rename to as_slice - /// TODO [Gav Wood] Please document me + /// Get the underlying byte-wise representation of the value. + /// Deprecated - use `as_slice` instead. fn bytes(&self) -> &[u8]; - /// TODO [Gav Wood] Please document me + /// Get the underlying byte-wise representation of the value. fn as_slice(&self) -> &[u8] { self.bytes() } - /// TODO [Gav Wood] Please document me + /// Get a copy of the underlying byte-wise representation. fn to_bytes(&self) -> Bytes { self.as_slice().to_vec() } } diff --git a/util/src/common.rs b/util/src/common.rs index 9cf7a3765..bfc883a6b 100644 --- a/util/src/common.rs +++ b/util/src/common.rs @@ -48,7 +48,7 @@ macro_rules! flushln { ($fmt:expr, $($arg:tt)*) => (flush!(concat!($fmt, "\n"), $($arg)*)); } -/// TODO [Gav Wood] Please document me +#[doc(hidden)] pub fn flush(s: String) { ::std::io::stdout().write(s.as_bytes()).unwrap(); ::std::io::stdout().flush().unwrap(); diff --git a/util/src/trie/triedbmut.rs b/util/src/trie/triedbmut.rs index 4c3d36646..e4e572609 100644 --- a/util/src/trie/triedbmut.rs +++ b/util/src/trie/triedbmut.rs @@ -72,7 +72,7 @@ impl<'db> TrieDBMut<'db> { // TODO: return Result pub fn from_existing(db: &'db mut HashDB, root: &'db mut H256) -> Self { if !db.exists(root) { - flush(format!("Trie root not found {}", root)); + flushln!("Trie root not found {}", root); panic!("Trie root not found!"); } TrieDBMut {