Merge pull request #192 from gavofyork/docs

Adding doc requests comments

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<U256>,				// Allowed to be Same
+	/// TODO [Gav Wood] Please document me
 	pub nonce: Diff<U256>,					// Allowed to be Same
+	/// TODO [Gav Wood] Please document me
 	pub code: Diff<Bytes>,					// Allowed to be Same
+	/// TODO [Gav Wood] Please document me
 	pub storage: BTreeMap<H256, Diff<H256>>,// 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<AccountDiff> {
 		match (pre, post) {
 			(None, Some(x)) => Some(AccountDiff {

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

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

src/block.rs

@@ -24,9 +24,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<Entry>,
+	/// TODO [Gav Wood] Please document me
 	pub uncles: &'a Vec<Header>,
 }
 

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<H256>,
+	/// 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
 }
 

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()) {

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

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.

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,

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<T: fmt::Debug> {
+	/// 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<T: fmt::Debug> {
+	/// TODO [Gav Wood] Please document me
 	pub min: Option<T>,
+	/// TODO [Gav Wood] Please document me
 	pub max: Option<T>,
+	/// TODO [Gav Wood] Please document me
 	pub found: T,
 }
 
@@ -22,58 +29,112 @@ pub struct OutOfBounds<T: fmt::Debug> {
 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<U256>),
 }
 
 #[derive(Debug, PartialEq, Eq)]
+/// TODO [arkpar] Please document me
 pub enum BlockError {
+	/// TODO [Gav Wood] Please document me
 	TooManyUncles(OutOfBounds<usize>),
+	/// TODO [Gav Wood] Please document me
 	UncleWrongGeneration,
+	/// TODO [Gav Wood] Please document me
 	ExtraDataOutOfBounds(OutOfBounds<usize>),
+	/// TODO [arkpar] Please document me
 	InvalidSealArity(Mismatch<usize>),
+	/// TODO [arkpar] Please document me
 	TooMuchGasUsed(OutOfBounds<U256>),
+	/// TODO [arkpar] Please document me
 	InvalidUnclesHash(Mismatch<H256>),
+	/// TODO [arkpar] Please document me
 	UncleTooOld(OutOfBounds<BlockNumber>),
+	/// TODO [arkpar] Please document me
 	UncleIsBrother(OutOfBounds<BlockNumber>),
+	/// TODO [arkpar] Please document me
 	UncleInChain(H256),
+	/// TODO [arkpar] Please document me
 	UncleParentNotInChain(H256),
+	/// TODO [arkpar] Please document me
 	InvalidStateRoot(Mismatch<H256>),
+	/// TODO [arkpar] Please document me
 	InvalidGasUsed(Mismatch<U256>),
+	/// TODO [arkpar] Please document me
 	InvalidTransactionsRoot(Mismatch<H256>),
+	/// TODO [arkpar] Please document me
 	InvalidDifficulty(Mismatch<U256>),
+	/// TODO [arkpar] Please document me
 	InvalidGasLimit(OutOfBounds<U256>),
+	/// TODO [arkpar] Please document me
 	InvalidReceiptsStateRoot(Mismatch<H256>),
+	/// TODO [arkpar] Please document me
 	InvalidTimestamp(OutOfBounds<u64>),
+	/// TODO [arkpar] Please document me
 	InvalidLogBloom(Mismatch<LogBloom>),
+	/// TODO [arkpar] Please document me
 	InvalidEthashDifficulty(Mismatch<U256>),
+	/// TODO [arkpar] Please document me
 	InvalidBlockNonce(Mismatch<H256>),
+	/// TODO [arkpar] Please document me
 	InvalidParentHash(Mismatch<H256>),
+	/// TODO [arkpar] Please document me
 	InvalidNumber(OutOfBounds<BlockNumber>),
+	/// 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<Error>),
+	/// 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),
 }
 

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

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<Engine> {
 		Box::new(Ethash {
 			spec: spec,

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

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.

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;

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
 }
 

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;

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

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<K, T>(&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<K, T>(&self, hash: &K) -> Option<T> where
 		T: ExtrasIndexable + Decodable,
 		K: ExtrasSliceConvertable;
 
+	/// TODO [debris] Please document me
 	fn extras_exists<K, T>(&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<H256>
 }
 
@@ -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<H2048>
 }
 
@@ -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
 }
 

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<Bytes>,
 
+	/// TODO [arkpar] Please document me
 	pub hash: RefCell<Option<H256>>,
+	/// TODO [Gav Wood] Please document me
 	pub bare_hash: RefCell<Option<H256>>,
 }
 
@@ -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<Bytes> { &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<Bytes>) { 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);
@@ -141,12 +177,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() }
 }
 

src/lib.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 #![feature(cell_extras)]
 #![feature(augmented_assignments)]
 //#![feature(plugin)]
@@ -88,31 +89,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;
@@ -120,9 +141,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;

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<H256>,
+	/// TODO [Gav Wood] Please document me
 	pub data: Bytes,
 }
 

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<Engine> {
 		Box::new(NullEngine{
 			spec: spec,

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<H256, H256>,
 }
 
@@ -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);

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<Address, PodAccount>);
 
 impl PodState {

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<PreVerifiedBlock> {
 		let mut verification = self.verification.lock().unwrap();
 		let count = min(max, verification.verified.len());

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<LogEntry>,
 }
 
 impl Receipt {
+	/// TODO [Gav Wood] Please document me
 	pub fn new(state_root: H256, gas_used: U256, logs: Vec<LogEntry>) -> Receipt {
 		Receipt {
 			state_root: state_root,

src/service.rs

@@ -33,10 +33,12 @@ impl ClientService {
 		})
 	}
 
+	/// TODO [arkpar] Please document me
 	pub fn io(&mut self) -> &mut IoService<NetSyncMessage> {
 		self.net_service.io()
 	}
 
+	/// TODO [arkpar] Please document me
 	pub fn client(&self) -> Arc<RwLock<Client>> {
 		self.client.clone()
 	}

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<String, Bytes>,
 
 	// Builtin-contracts are here for now but would like to abstract into Engine API eventually.
+	/// TODO [Gav Wood] Please document me
 	pub builtins: HashMap<Address, Builtin>,
 
 	// 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<Address, GenesisAccount>,
+	/// 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.
@@ -112,6 +127,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(),

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<Receipt, Error>;
 
 /// 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;
 	}

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<Address, AccountDiff>);
 
 impl StateDiff {

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

src/sync/mod.rs

@@ -46,6 +46,7 @@ pub enum SyncMessage {
 	BlockVerified,
 }
 
+/// TODO [arkpar] Please document me
 pub type NetSyncMessage = NetworkIoMessage<SyncMessage>;
 
 /// Ethereum network protocol handler

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<Option<H256>>,
@@ -30,6 +42,7 @@ pub struct Transaction {
 }
 
 impl Transaction {
+	/// TODO [Gav Wood] Please document me
 	pub fn new() -> Self {
 		Transaction {
 			nonce: x!(0),

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<u8>;
 /// 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<u8>;
+	/// 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<u8> { self.to_bytes().first().map(|&x| { x })}
 }
 
@@ -257,7 +270,9 @@ impl <T>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<T> = Result<T, FromBytesError>;
 ///
 /// 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<Self>;
 }
 

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

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

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<Signature, CryptoError> { 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<Secret, CryptoError> {
 		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<Bytes, CryptoError> {
 		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<Bytes, CryptoError> {
 		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");

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

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

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<T>(mut self, b: &T) -> Self where T: FixedHash { self.shift_bloomed(b); self }
+	/// TODO [Gav Wood] Please document me
 	fn bloom_part<T>(&self, m: usize) -> T where T: FixedHash;
+	/// TODO [debris] Please document me
 	fn contains_bloomed<T>(&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<T>(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)

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<Message>: 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<M> = service::IoService<M>;
+/// TODO [arkpar] Please document me
 pub type IoChannel<M> = service::IoChannel<M>;
 //pub const USER_TOKEN_START: usize = service::USER_TOKEN; // TODO: ICE in rustc 1.7.0-nightly (49c382779 2016-01-12)
 

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

util/src/lib.rs

@@ -1,3 +1,4 @@
+#![warn(missing_docs)]
 #![feature(op_assign_traits)]
 #![feature(augmented_assignments)]
 #![feature(associated_consts)]
@@ -51,17 +52,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;
@@ -69,16 +75,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::*;

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

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<T> 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<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
 	Clean,
+	/// TODO [Gav Wood] Please document me
 	Dirty,
 }

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<Message> = service::NetworkService<Message>;
+/// TODO [arkpar] Please document me
 pub type NetworkIoMessage<Message> = host::NetworkIoMessage<Message>;
 pub use network::host::NetworkIoMessage::User as UserMessage;
+/// TODO [arkpar] Please document me
 pub type NetworkError = error::NetworkError;
 
 use io::*;

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

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

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

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<T>(&self) -> T where T: Decodable {
 		Self::view_as_val(self)
 	}
 
+	/// TODO [debris] Please document me
 	pub fn val_at<T>(&self, index: usize) -> T where T: Decodable {
 		Self::view_as_val(&self.at(index))
 	}

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

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<T, F>(&self, f: F) -> Result<T, DecoderError>
 		where F: FnOnce(&[u8]) -> Result<T, DecoderError>;
 
+	/// TODO [arkpar] Please document me
 	fn as_list(&self) -> Result<Vec<Self>, DecoderError>;
+	/// TODO [Gav Wood] Please document me
 	fn as_rlp<'a>(&'a self) -> &'a UntrustedRlp<'a>;
+	/// 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<D>(decoder: &D) -> Result<Self, DecoderError>  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<T>(&self) -> Result<T, DecoderError> where T: Decodable;
 
+	/// TODO [debris] Please document me
 	fn val_at<T>(&self, index: usize) -> Result<T, DecoderError> 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<F>(&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<E>(&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.

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

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

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

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

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

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

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

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

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<u64> + 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<Self, Self::FromDecStrErr>;
 
 	/// Conversion to u32
@@ -98,18 +103,25 @@ pub trait Uint: Sized + Default + FromStr + From<u64> + 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<U256> 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)]

util/src/vector.rs

@@ -2,7 +2,9 @@
 
 use std::ptr;
 
+/// TODO [debris] Please document me
 pub trait InsertSlice<T> {
+				/// TODO [debris] Please document me
     fn insert_slice(&mut self, index: usize, elements: &[T]);
 }
 
@@ -47,6 +49,7 @@ impl<T> InsertSlice<T> for Vec<T> {
 ///	}
 /// ```
 pub trait SharedPrefix <T> {
+	/// TODO [debris] Please document me
 	fn shared_prefix_len(&self, elem: &[T]) -> usize;
 }