Merge pull request #320 from ethcore/gavdocs

Finish all my docs. Fix previous test compilation.

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<HashMap<H256, (Filth, H256)>> { self.storage_overlay.borrow() }
 

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<AccountDiff> {
 		match (pre, post) {
 			(None, Some(x)) => Some(AccountDiff {

ethcore/src/state.rs

@@ -2,6 +2,7 @@ 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.
 
@@ -194,6 +195,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<Address, PodAccount> {
 		// TODO: handle database rather than just the cache.
 		self.cache.borrow().iter().fold(HashMap::new(), |mut m, (add, opt)| {

ethcore/src/state_diff.rs

@@ -9,6 +9,7 @@ pub struct StateDiff (BTreeMap<Address, AccountDiff>);
 
 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())
 	}

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<Transaction, Error> {
 		if require_low && !ec::is_low_s(&self.s) {
 			return Err(Error::Util(UtilError::Crypto(CryptoError::InvalidSignature)));

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! {

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,
 }
 

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;
 }

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<T>(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<T>(&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<T>(&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<T>(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)

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..]

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<H256, (Bytes, i32)> {
 		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 {

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<T> 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<T> Diff<T> 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,
 }

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);

util/src/rlp/bytes.rs

@@ -236,7 +236,7 @@ impl_uint_from_bytes!(U128);
 
 impl <T>FromBytes for T where T: FixedHash {
 	fn from_bytes(bytes: &[u8]) -> FromBytesResult<T> {
-		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 <T>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)
 		}

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

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
 }
 

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<T, F>(&self, f: F) -> Result<T, DecoderError>
 		where F: FnOnce(&[u8]) -> Result<T, DecoderError>;
 
-	/// 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];
 }
 

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] );
 
 

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::*;

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]>)
 }
 

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),
 }
 

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,
 }
 

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,
 }
 

util/src/uint.rs

@@ -60,20 +60,20 @@ macro_rules! panic_on_overflow {
 	}
 }
 
-/// Generic Uint of unspecified size
+/// Large, fixed-length unsigned integer type.
 pub trait Uint: Sized + Default + FromStr + From<u64> + FromJson + fmt::Debug + fmt::Display + PartialOrd + Ord + PartialEq + Eq + Hash {
 
 	/// Size of this type.
 	const SIZE: usize;
 
-	/// Returns `Uint(0)`
+	/// Returns new instance equalling zero.
 	fn zero() -> Self;
-	/// Returns `Uint(1)`
+	/// Returns new instance equalling one.
 	fn one() -> Self;
 
-	/// Error returned when `from_dec_str` method fails
+	/// Error type for converting from a decimal string.
 	type FromDecStrErr;
-	/// Create `Uint` from specified decimal represented by string
+	/// Convert from a decimal string.
 	fn from_dec_str(value: &str) -> Result<Self, Self::FromDecStrErr>;
 
 	/// Conversion to u32
@@ -104,7 +104,6 @@ pub trait Uint: Sized + Default + FromStr + From<u64> + FromJson + fmt::Debug +
 	/// Return wrapped eponentation `self**other` and flag if there was an overflow
 	fn overflowing_pow(self, other: Self) -> (Self, bool);
 
-
 	/// Add this `Uint` to other returning result and possible overflow
 	fn overflowing_add(self, other: Self) -> (Self, bool);
 
@@ -939,12 +938,10 @@ impl From<U256> 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 {