From 3f03ba40eebb95fce23240b442c040dec5b9a5da Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Wed, 3 Feb 2016 13:32:57 +0100 Subject: [PATCH 1/2] Suppress warnings along with explanation. --- ethcore/src/account.rs | 11 +++++------ ethcore/src/account_diff.rs | 3 ++- ethcore/src/state.rs | 3 ++- ethcore/src/state_diff.rs | 1 + ethcore/src/transaction.rs | 1 + 5 files changed, 11 insertions(+), 8 deletions(-) diff --git a/ethcore/src/account.rs b/ethcore/src/account.rs index 0d535f7ce..24386e839 100644 --- a/ethcore/src/account.rs +++ b/ethcore/src/account.rs @@ -35,6 +35,7 @@ impl Account { } /// General constructor. + #[allow(dead_code)] // Used only in test code for now. pub fn from_pod(pod: PodAccount) -> Account { Account { balance: pod.balance, @@ -110,6 +111,7 @@ impl Account { pub fn nonce(&self) -> &U256 { &self.nonce } /// return the code hash associated with this account. + #[allow(dead_code)] // Used only in test code for now. pub fn code_hash(&self) -> H256 { self.code_hash.clone().unwrap_or(SHA3_EMPTY) } @@ -126,6 +128,7 @@ impl Account { } /// Provide a byte array which hashes to the `code_hash`. returns the hash as a result. + #[allow(dead_code)] // Used only in test code for now. pub fn note_code(&mut self, code: Bytes) -> Result<(), H256> { let h = code.sha3(); match self.code_hash { @@ -159,18 +162,14 @@ impl Account { } } - /// return the storage root associated with this account. - pub fn base_root(&self) -> &H256 { &self.storage_root } - /// Determine whether there are any un-`commit()`-ed storage-setting operations. + #[allow(dead_code)] pub fn storage_is_clean(&self) -> bool { self.storage_overlay.borrow().iter().find(|&(_, &(f, _))| f == Filth::Dirty).is_none() } /// return the storage root associated with this account or None if it has been altered via the overlay. + #[allow(dead_code)] pub fn storage_root(&self) -> Option<&H256> { if self.storage_is_clean() {Some(&self.storage_root)} else {None} } - /// return the storage root associated with this account or None if it has been altered via the overlay. - pub fn recent_storage_root(&self) -> &H256 { &self.storage_root } - /// return the storage overlay. pub fn storage_overlay(&self) -> Ref> { self.storage_overlay.borrow() } diff --git a/ethcore/src/account_diff.rs b/ethcore/src/account_diff.rs index 411150739..72c331959 100644 --- a/ethcore/src/account_diff.rs +++ b/ethcore/src/account_diff.rs @@ -49,8 +49,9 @@ impl AccountDiff { } } - /// Determine difference between two optionally existance `Account`s. Returns None + /// Determine difference between two optionally existant `Account`s. Returns None /// if they are the same. + #[allow(dead_code)] // Used only in test code for now. pub fn diff_pod(pre: Option<&PodAccount>, post: Option<&PodAccount>) -> Option { match (pre, post) { (None, Some(x)) => Some(AccountDiff { diff --git a/ethcore/src/state.rs b/ethcore/src/state.rs index 3c12804b9..d285f0e0d 100644 --- a/ethcore/src/state.rs +++ b/ethcore/src/state.rs @@ -2,7 +2,6 @@ use common::*; use engine::Engine; use executive::Executive; use pod_account::*; -use pod_state::PodState; //use state_diff::*; // TODO: uncomment once to_pod() works correctly. /// Result type for the execution ("application") of a transaction. @@ -194,6 +193,7 @@ impl State { } /// Populate a PodAccount map from this state. + #[allow(dead_code)] // Used only in test code for now. pub fn to_hashmap_pod(&self) -> HashMap { // TODO: handle database rather than just the cache. self.cache.borrow().iter().fold(HashMap::new(), |mut m, (add, opt)| { @@ -273,6 +273,7 @@ use util::rlp::*; use util::uint::*; use account::*; use tests::helpers::*; +use pod_state::PodState; #[test] fn code_from_database() { diff --git a/ethcore/src/state_diff.rs b/ethcore/src/state_diff.rs index 1caa62ef1..b3bc4b4e5 100644 --- a/ethcore/src/state_diff.rs +++ b/ethcore/src/state_diff.rs @@ -9,6 +9,7 @@ pub struct StateDiff (BTreeMap); impl StateDiff { /// Calculate and return diff between `pre` state and `post` state. + #[allow(dead_code)] // Used only in test code for now. pub fn diff_pod(pre: &PodState, post: &PodState) -> StateDiff { StateDiff(pre.get().keys().merge(post.get().keys()).filter_map(|acc| AccountDiff::diff_pod(pre.get().get(acc), post.get().get(acc)).map(|d|(acc.clone(), d))).collect()) } diff --git a/ethcore/src/transaction.rs b/ethcore/src/transaction.rs index bc777d7ae..3b9d0e162 100644 --- a/ethcore/src/transaction.rs +++ b/ethcore/src/transaction.rs @@ -230,6 +230,7 @@ impl Transaction { } /// Do basic validation, checking for valid signature and minimum gas, + #[allow(dead_code)] // Used only in tests. TODO: consider use in block validation. pub fn validate(self, schedule: &Schedule, require_low: bool) -> Result { if require_low && !ec::is_low_s(&self.s) { return Err(Error::Util(UtilError::Crypto(CryptoError::InvalidSignature))); From fad2f3a23d5d51beaa3d6777643db36c6b2c6dc1 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Wed, 3 Feb 2016 14:51:45 +0100 Subject: [PATCH 2/2] More doc updates. All Gav Wood docs done. --- ethcore/src/state.rs | 3 ++- util/src/crypto.rs | 7 +++--- util/src/error.rs | 26 +++++++++---------- util/src/from_json.rs | 4 +-- util/src/hash.rs | 48 +++++++++++++++++++----------------- util/src/json_aid.rs | 2 +- util/src/memorydb.rs | 7 ++++-- util/src/misc.rs | 12 ++++----- util/src/nibbleslice.rs | 9 ++++--- util/src/rlp/bytes.rs | 4 +-- util/src/rlp/mod.rs | 8 +++--- util/src/rlp/rlperrors.rs | 22 ++++++++--------- util/src/rlp/rlptraits.rs | 8 +++--- util/src/sha3.rs | 2 +- util/src/trie/mod.rs | 15 +++++------ util/src/trie/node.rs | 8 +++--- util/src/trie/standardmap.rs | 8 +++--- util/src/trie/triedb.rs | 2 +- util/src/trie/triedbmut.rs | 2 +- util/src/uint.rs | 30 +++++++++++----------- 20 files changed, 117 insertions(+), 110 deletions(-) diff --git a/ethcore/src/state.rs b/ethcore/src/state.rs index d285f0e0d..0fbdc194a 100644 --- a/ethcore/src/state.rs +++ b/ethcore/src/state.rs @@ -2,6 +2,8 @@ use common::*; use engine::Engine; use executive::Executive; use pod_account::*; +#[cfg(test)] +use pod_state::PodState; //use state_diff::*; // TODO: uncomment once to_pod() works correctly. /// Result type for the execution ("application") of a transaction. @@ -273,7 +275,6 @@ use util::rlp::*; use util::uint::*; use account::*; use tests::helpers::*; -use pod_state::PodState; #[test] fn code_from_database() { diff --git a/util/src/crypto.rs b/util/src/crypto.rs index 8a56c8827..845bb4798 100644 --- a/util/src/crypto.rs +++ b/util/src/crypto.rs @@ -6,11 +6,12 @@ use uint::*; use secp256k1::{key, Secp256k1}; use rand::os::OsRng; -/// TODO [Gav Wood] Please document me +/// Secret key for secp256k1 EC operations. 256 bit generic "hash" data. pub type Secret = H256; -/// TODO [Gav Wood] Please document me +/// Public key for secp256k1 EC operations. 512 bit generic "hash" data. pub type Public = H512; -/// TODO [Gav Wood] Please document me +/// Signature for secp256k1 EC operations; encodes two 256-bit curve points +/// and a third sign bit. 520 bit generic "hash" data. pub type Signature = H520; lazy_static! { diff --git a/util/src/error.rs b/util/src/error.rs index 0d13d329c..4d2e0943b 100644 --- a/util/src/error.rs +++ b/util/src/error.rs @@ -6,36 +6,36 @@ use rlp::DecoderError; use io; #[derive(Debug)] -/// TODO [Gav Wood] Please document me +/// Error in database subsystem. pub enum BaseDataError { - /// TODO [Gav Wood] Please document me + /// An entry was removed more times than inserted. 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 + /// Error concerning the crypto utility subsystem. Crypto(::crypto::CryptoError), - /// TODO [Gav Wood] Please document me + /// Error concerning the Rust standard library's IO subsystem. StdIo(::std::io::Error), - /// TODO [Gav Wood] Please document me + /// Error concerning our IO utility subsystem. Io(io::IoError), - /// TODO [Gav Wood] Please document me + /// Error concerning the network address parsing subsystem. AddressParse(::std::net::AddrParseError), - /// TODO [Gav Wood] Please document me + /// Error concerning the network address resolution subsystem. AddressResolve(Option<::std::io::Error>), - /// TODO [Gav Wood] Please document me + /// Error concerning the hex conversion logic. FromHex(FromHexError), - /// TODO [Gav Wood] Please document me + /// Error concerning the database abstraction logic. BaseData(BaseDataError), - /// TODO [Gav Wood] Please document me + /// Error concerning the network subsystem. Network(NetworkError), - /// TODO [Gav Wood] Please document me + /// Error concerning the RLP decoder. Decoder(DecoderError), - /// TODO [Gav Wood] Please document me + /// Miscellaneous error described by a string. SimpleString(String), - /// TODO [Gav Wood] Please document me + /// Error from a bad input size being given for the needed output. BadSize, } diff --git a/util/src/from_json.rs b/util/src/from_json.rs index 7319ec8aa..63469ea61 100644 --- a/util/src/from_json.rs +++ b/util/src/from_json.rs @@ -9,8 +9,8 @@ macro_rules! xjson { } } -/// TODO [Gav Wood] Please document me +/// Trait allowing conversion from a JSON value. pub trait FromJson { - /// TODO [Gav Wood] Please document me + /// Convert a JSON value to an instance of this type. fn from_json(json: &Json) -> Self; } diff --git a/util/src/hash.rs b/util/src/hash.rs index b3154b57a..68611f7b4 100644 --- a/util/src/hash.rs +++ b/util/src/hash.rs @@ -15,35 +15,35 @@ use serde; /// /// Note: types implementing `FixedHash` must be also `BytesConvertable`. pub trait FixedHash: Sized + BytesConvertable + Populatable + FromStr + Default { - /// TODO [Gav Wood] Please document me + /// Create a new, zero-initialised, instance. fn new() -> Self; /// Synonym for `new()`. Prefer to new as it's more readable. fn zero() -> Self; - /// TODO [debris] Please document me + /// Create a new, cryptographically random, instance. fn random() -> Self; - /// TODO [debris] Please document me + /// Assign self have a cryptographically random value. fn randomize(&mut self); - /// TODO [arkpar] Please document me - fn size() -> usize; - /// TODO [arkpar] Please document me + /// Get the size of this object in bytes. + fn len() -> usize; + /// Convert a slice of bytes of length `len()` to an instance of this type. fn from_slice(src: &[u8]) -> Self; - /// TODO [arkpar] Please document me + /// Assign self to be of the same value as a slice of bytes of length `len()`. fn clone_from_slice(&mut self, src: &[u8]) -> usize; - /// TODO [Gav Wood] Please document me + /// Copy the data of this object into some mutable slice of length `len()`. fn copy_to(&self, dest: &mut [u8]); - /// TODO [Gav Wood] Please document me + /// When interpreting self as a bloom output, augment (bit-wise OR) with the a bloomed version of `b`. fn shift_bloomed<'a, T>(&'a mut self, b: &T) -> &'a mut Self where T: FixedHash; - /// TODO [debris] Please document me + /// Same as `shift_bloomed` except that `self` is consumed and a new value returned. fn with_bloomed(mut self, b: &T) -> Self where T: FixedHash { self.shift_bloomed(b); self } - /// TODO [Gav Wood] Please document me + /// Bloom the current value using the bloom parameter `m`. fn bloom_part(&self, m: usize) -> T where T: FixedHash; - /// TODO [debris] Please document me + /// Check to see whether this hash, interpreted as a bloom, contains the value `b` when bloomed. fn contains_bloomed(&self, b: &T) -> bool where T: FixedHash; - /// TODO [arkpar] Please document me + /// Returns `true` if all bits set in `b` are also set in `self`. fn contains<'a>(&'a self, b: &'a Self) -> bool; - /// TODO [debris] Please document me + /// Returns `true` if no bits are set. fn is_zero(&self) -> bool; - /// Return the lowest 8 bytes interpreted as a BigEndian integer. + /// Returns the lowest 8 bytes interpreted as a BigEndian integer. fn low_u64(&self) -> u64; } @@ -58,7 +58,7 @@ fn clean_0x(s: &str) -> &str { macro_rules! impl_hash { ($from: ident, $size: expr) => { #[derive(Eq)] - /// TODO [Gav Wood] Please document me + /// Unformatted binary data of fixed length. pub struct $from (pub [u8; $size]); impl BytesConvertable for $from { @@ -103,7 +103,7 @@ macro_rules! impl_hash { rng.fill_bytes(&mut self.0); } - fn size() -> usize { + fn len() -> usize { $size } @@ -457,12 +457,12 @@ macro_rules! impl_hash { } impl $from { - /// TODO [Gav Wood] Please document me + /// Get a hex representation. pub fn hex(&self) -> String { format!("{:?}", self) } - /// TODO [Gav Wood] Please document me + /// Construct new instance equal to the bloomed value of `b`. pub fn from_bloomed(b: &T) -> Self where T: FixedHash { b.bloom_part($size) } } @@ -578,25 +578,27 @@ impl<'_> From<&'_ Address> for H256 { } } -/// TODO [Gav Wood] Please document me +/// Convert string `s` to an `H256`. Will panic if `s` is not 64 characters long or if any of +/// those characters are not 0-9, a-z or A-Z. pub fn h256_from_hex(s: &str) -> H256 { use std::str::FromStr; H256::from_str(s).unwrap() } -/// TODO [Gav Wood] Please document me +/// Convert `n` to an `H256`, setting the rightmost 8 bytes. pub fn h256_from_u64(n: u64) -> H256 { use uint::U256; H256::from(&U256::from(n)) } -/// TODO [Gav Wood] Please document me +/// Convert string `s` to an `Address`. Will panic if `s` is not 40 characters long or if any of +/// those characters are not 0-9, a-z or A-Z. pub fn address_from_hex(s: &str) -> Address { use std::str::FromStr; Address::from_str(s).unwrap() } -/// TODO [Gav Wood] Please document me +/// Convert `n` to an `Address`, setting the rightmost 8 bytes. pub fn address_from_u64(n: u64) -> Address { let h256 = h256_from_u64(n); From::from(h256) diff --git a/util/src/json_aid.rs b/util/src/json_aid.rs index 5974c5989..7ca75a34f 100644 --- a/util/src/json_aid.rs +++ b/util/src/json_aid.rs @@ -1,6 +1,6 @@ use common::*; -/// TODO [Gav Wood] Please document me +/// Remove the `"0x"`, if present, from the left of `s`, returning the remaining slice. pub fn clean(s: &str) -> &str { if s.len() >= 2 && &s[0..2] == "0x" { &s[2..] diff --git a/util/src/memorydb.rs b/util/src/memorydb.rs index f2935cceb..71addda3c 100644 --- a/util/src/memorydb.rs +++ b/util/src/memorydb.rs @@ -107,14 +107,17 @@ impl MemoryDB { self.data.get(key) } - /// TODO [Gav Wood] Please document me + /// Return the internal map of hashes to data, clearing the current state. 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 + /// Denote than an existing value has the given key. Used when a key gets removed without + /// a prior insert and thus has a negative reference with no value. + /// + /// May safely be called even if the key's value is known, in which case it will be a no-op. 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 f0e34d4c9..2c98179f3 100644 --- a/util/src/misc.rs +++ b/util/src/misc.rs @@ -5,13 +5,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 + /// Both sides are the same. Same, - /// TODO [Gav Wood] Please document me + /// Left (pre, source) side doesn't include value, right side (post, destination) does. Born(T), - /// TODO [Gav Wood] Please document me + /// Both sides include data; it chaged value between them. Changed(T, T), - /// TODO [Gav Wood] Please document me + /// Left (pre, source) side does include value, right side (post, destination) does not. Died(T), } @@ -32,8 +32,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 + /// Data has not been changed. Clean, - /// TODO [Gav Wood] Please document me + /// Data has been changed. Dirty, } diff --git a/util/src/nibbleslice.rs b/util/src/nibbleslice.rs index c0d076440..ac87b808f 100644 --- a/util/src/nibbleslice.rs +++ b/util/src/nibbleslice.rs @@ -34,7 +34,7 @@ pub struct NibbleSlice<'a> { offset_encode_suffix: usize, } -/// TODO [Gav Wood] Please document me +/// Iterator type for a nibble slice. pub struct NibbleSliceIterator<'a> { p: &'a NibbleSlice<'a>, i: usize, @@ -77,7 +77,7 @@ impl<'a, 'view> NibbleSlice<'a> where 'a: 'view { (r, a.len() + b.len()) }*/ - /// TODO [Gav Wood] Please document me + /// Get an iterator for the series of nibbles. pub fn iter(&'a self) -> NibbleSliceIterator<'a> { NibbleSliceIterator { p: self, i: 0 } } @@ -132,7 +132,7 @@ impl<'a, 'view> NibbleSlice<'a> where 'a: 'view { i } - /// TODO [Gav Wood] Please document me + /// Encode while nibble slice in prefixed hex notation, noting whether it `is_leaf`. pub fn encoded(&self, is_leaf: bool) -> Bytes { let l = self.len(); let mut r = Bytes::with_capacity(l / 2 + 1); @@ -145,7 +145,8 @@ impl<'a, 'view> NibbleSlice<'a> where 'a: 'view { r } - /// TODO [Gav Wood] Please document me + /// Encode only the leftmost `n` bytes of the nibble slice in prefixed hex notation, + /// noting whether it `is_leaf`. 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/bytes.rs b/util/src/rlp/bytes.rs index 69562764c..b61744977 100644 --- a/util/src/rlp/bytes.rs +++ b/util/src/rlp/bytes.rs @@ -236,7 +236,7 @@ impl_uint_from_bytes!(U128); impl FromBytes for T where T: FixedHash { fn from_bytes(bytes: &[u8]) -> FromBytesResult { - match bytes.len().cmp(&T::size()) { + match bytes.len().cmp(&T::len()) { Ordering::Less => return Err(FromBytesError::DataIsTooShort), Ordering::Greater => return Err(FromBytesError::DataIsTooLong), Ordering::Equal => () @@ -246,7 +246,7 @@ impl FromBytes for T where T: FixedHash { use std::{mem, ptr}; let mut res: T = mem::uninitialized(); - ptr::copy(bytes.as_ptr(), res.as_slice_mut().as_mut_ptr(), T::size()); + ptr::copy(bytes.as_ptr(), res.as_slice_mut().as_mut_ptr(), T::len()); Ok(res) } diff --git a/util/src/rlp/mod.rs b/util/src/rlp/mod.rs index f6101abc6..fb2ee3d5a 100644 --- a/util/src/rlp/mod.rs +++ b/util/src/rlp/mod.rs @@ -48,13 +48,13 @@ pub use self::rlpstream::{RlpStream}; pub use elastic_array::ElasticArray1024; use super::hash::H256; -/// TODO [arkpar] Please document me +/// The RLP encoded empty data (used to mean "null value"). pub const NULL_RLP: [u8; 1] = [0x80; 1]; -/// TODO [Gav Wood] Please document me +/// The RLP encoded empty list. pub const EMPTY_LIST_RLP: [u8; 1] = [0xC0; 1]; -/// TODO [arkpar] Please document me +/// The SHA3 of the RLP encoding of empty data. 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 +/// The SHA3 of the RLP encoding of empty list. 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 f5d4629ad..d032ab36a 100644 --- a/util/src/rlp/rlperrors.rs +++ b/util/src/rlp/rlperrors.rs @@ -3,27 +3,27 @@ use std::error::Error as StdError; use rlp::bytes::FromBytesError; #[derive(Debug, PartialEq, Eq)] -/// TODO [debris] Please document me +/// Error concerning the RLP decoder. pub enum DecoderError { - /// TODO [debris] Please document me + /// Couldn't convert given bytes to an instance of required type. FromBytesError(FromBytesError), - /// Given data has additional bytes at the end of the valid RLP fragment. + /// Data has additional bytes at the end of the valid RLP fragment. RlpIsTooBig, - /// TODO [debris] Please document me + /// Data has too few bytes for valid RLP. RlpIsTooShort, - /// TODO [debris] Please document me + /// Expect an encoded list, RLP was something else. RlpExpectedToBeList, - /// TODO [Gav Wood] Please document me + /// Expect encoded data, RLP was something else. RlpExpectedToBeData, - /// TODO [Gav Wood] Please document me + /// Expected a different size list. RlpIncorrectListLen, - /// TODO [Gav Wood] Please document me + /// Data length number has a prefixed zero byte, invalid for numbers. RlpDataLenWithZeroPrefix, - /// TODO [Gav Wood] Please document me + /// List length number has a prefixed zero byte, invalid for numbers. RlpListLenWithZeroPrefix, - /// TODO [debris] Please document me + /// Non-canonical (longer than necessary) representation used for data or list. RlpInvalidIndirection, - /// Returned when declared length is inconsistent with data specified after + /// Declared length is inconsistent with data specified after. RlpInconsistentLengthAndData } diff --git a/util/src/rlp/rlptraits.rs b/util/src/rlp/rlptraits.rs index 17acbb40b..c660fbe1e 100644 --- a/util/src/rlp/rlptraits.rs +++ b/util/src/rlp/rlptraits.rs @@ -7,15 +7,15 @@ use elastic_array::ElasticArray1024; use hash::H256; use sha3::*; -/// TODO [debris] Please document me +/// Type is able to decode RLP. pub trait Decoder: Sized { - /// TODO [debris] Please document me + /// Read a value from the RLP into a given type. fn read_value(&self, f: F) -> Result where F: FnOnce(&[u8]) -> Result; - /// TODO [Gav Wood] Please document me + /// Get underlying `UntrustedRLP` object. fn as_rlp(&self) -> &UntrustedRlp; - /// TODO [debris] Please document me + /// Get underlying raw bytes slice. fn as_raw(&self) -> &[u8]; } diff --git a/util/src/sha3.rs b/util/src/sha3.rs index 115a408de..d00516000 100644 --- a/util/src/sha3.rs +++ b/util/src/sha3.rs @@ -6,7 +6,7 @@ use bytes::{BytesConvertable, Populatable}; use hash::{H256, FixedHash}; use self::sha3_ext::*; -/// TODO [Gav Wood] Please document me +/// Get the SHA3 (i.e. Keccak) hash of the empty bytes string. 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/trie/mod.rs b/util/src/trie/mod.rs index 502a7688d..74a525bb6 100644 --- a/util/src/trie/mod.rs +++ b/util/src/trie/mod.rs @@ -1,19 +1,20 @@ //! Trie interface and implementation. -/// TODO [Gav Wood] Please document me +/// Export the trietraits module. pub mod trietraits; +/// Export the standardmap module. pub mod standardmap; -/// TODO [Gav Wood] Please document me +/// Export the journal module. pub mod journal; -/// TODO [Gav Wood] Please document me +/// Export the node module. pub mod node; -/// TODO [Gav Wood] Please document me +/// Export the triedb module. pub mod triedb; -/// TODO [Gav Wood] Please document me +/// Export the triedbmut module. pub mod triedbmut; -/// TODO [Gav Wood] Please document me +/// Export the sectriedb module. pub mod sectriedb; -/// TODO [Gav Wood] Please document me +/// Export the sectriedbmut module. pub mod sectriedbmut; pub use self::trietraits::*; diff --git a/util/src/trie/node.rs b/util/src/trie/node.rs index c47a0d25f..626c4dd00 100644 --- a/util/src/trie/node.rs +++ b/util/src/trie/node.rs @@ -7,13 +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 + /// Null trie node; could be an empty root or an empty branch entry. Empty, - /// TODO [Gav Wood] Please document me + /// Leaf node; has key slice and value. Value may not be empty. Leaf(NibbleSlice<'a>, &'a[u8]), - /// TODO [Gav Wood] Please document me + /// Extension node; has key slice and node data. Data may not be null. Extension(NibbleSlice<'a>, &'a[u8]), - /// TODO [Gav Wood] Please document me + /// Branch node; has array of 16 child nodes (each possibly null) and an optional immediate node data. Branch([&'a[u8]; 16], Option<&'a [u8]>) } diff --git a/util/src/trie/standardmap.rs b/util/src/trie/standardmap.rs index 4573efd66..ce2062566 100644 --- a/util/src/trie/standardmap.rs +++ b/util/src/trie/standardmap.rs @@ -7,13 +7,13 @@ use hash::*; /// Alphabet to use when creating words for insertion into tries. pub enum Alphabet { - /// TODO [Gav Wood] Please document me + /// All values are allowed in each bytes of the key. All, - /// TODO [Gav Wood] Please document me + /// Only a 6 values ('a' - 'f') are chosen to compose the key. Low, - /// TODO [Gav Wood] Please document me + /// Quite a few values (around 32) are chosen to compose the key. Mid, - /// TODO [Gav Wood] Please document me + /// A set of bytes given is used to compose the key. Custom(Bytes), } diff --git a/util/src/trie/triedb.rs b/util/src/trie/triedb.rs index 7179c395e..9909c05a4 100644 --- a/util/src/trie/triedb.rs +++ b/util/src/trie/triedb.rs @@ -34,7 +34,7 @@ use super::node::*; pub struct TrieDB<'db> { db: &'db HashDB, root: &'db H256, - /// TODO [Gav Wood] Please document me + /// The number of hashes performed so far in operations on this trie. pub hash_count: usize, } diff --git a/util/src/trie/triedbmut.rs b/util/src/trie/triedbmut.rs index e4e572609..f65d196e4 100644 --- a/util/src/trie/triedbmut.rs +++ b/util/src/trie/triedbmut.rs @@ -40,7 +40,7 @@ use super::trietraits::*; pub struct TrieDBMut<'db> { db: &'db mut HashDB, root: &'db mut H256, - /// TODO [Gav Wood] Please document me + /// The number of hashes performed so far in operations on this trie. pub hash_count: usize, } diff --git a/util/src/uint.rs b/util/src/uint.rs index 7eee6029e..4deee5837 100644 --- a/util/src/uint.rs +++ b/util/src/uint.rs @@ -60,20 +60,20 @@ macro_rules! panic_on_overflow { } } -/// TODO [Gav Wood] Please document me +/// Large, fixed-length unsigned integer type. 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 + /// Returns new instance equalling zero. fn zero() -> Self; - /// TODO [Gav Wood] Please document me + /// Returns new instance equalling one. fn one() -> Self; - /// TODO [Gav Wood] Please document me + /// Error type for converting from a decimal string. type FromDecStrErr; - /// TODO [Gav Wood] Please document me + /// Convert from a decimal string. fn from_dec_str(value: &str) -> Result; /// Conversion to u32 @@ -105,25 +105,25 @@ pub trait Uint: Sized + Default + FromStr + From + FromJson + fmt::Debug + fn overflowing_pow(self, other: Self) -> (Self, bool); - /// TODO [debris] Please document me + /// Overflowing addition operation. fn overflowing_add(self, other: Self) -> (Self, bool); - /// TODO [debris] Please document me + /// Overflowing subtract operation. fn overflowing_sub(self, other: Self) -> (Self, bool); - /// TODO [debris] Please document me + /// Overflowing multiply operation. fn overflowing_mul(self, other: Self) -> (Self, bool); - /// TODO [debris] Please document me + /// Overflowing divide operation. fn overflowing_div(self, other: Self) -> (Self, bool); - /// TODO [debris] Please document me + /// Overflowing remainder operation. fn overflowing_rem(self, other: Self) -> (Self, bool); - /// TODO [debris] Please document me + /// Overflowing negative operation. fn overflowing_neg(self) -> (Self, bool); - /// TODO [Gav Wood] Please document me + /// Overflowing left bit shift. fn overflowing_shl(self, shift: u32) -> (Self, bool); } @@ -939,12 +939,10 @@ impl From for u32 { } } -/// TODO [Gav Wood] Please document me +/// Constant value of `U256::zero()` that can be used for a reference saving an additional instance creation. pub const ZERO_U256: U256 = U256([0x00u64; 4]); -/// TODO [Gav Wood] Please document me +/// Constant value of `U256::one()` that can be used for a reference saving an additional instance creation. 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)] mod tests {