diff --git a/ethcore/src/error.rs b/ethcore/src/error.rs
index 96a362025..2d6753e95 100644
--- a/ethcore/src/error.rs
+++ b/ethcore/src/error.rs
@@ -5,22 +5,22 @@ use header::BlockNumber;
 use basic_types::LogBloom;
 
 #[derive(Debug, PartialEq, Eq)]
-/// TODO [Gav Wood] Please document me
+/// Error indicating an expected value was not found.
 pub struct Mismatch<T: fmt::Debug> {
-	/// TODO [Gav Wood] Please document me
+	/// Value expected.
 	pub expected: T,
-	/// TODO [Gav Wood] Please document me
+	/// Value found.
 	pub found: T,
 }
 
 #[derive(Debug, PartialEq, Eq)]
-/// TODO [Gav Wood] Please document me
+/// Error indicating value found is outside of a valid range.
 pub struct OutOfBounds<T: fmt::Debug> {
-	/// TODO [Gav Wood] Please document me
+	/// Minimum allowed value.
 	pub min: Option<T>,
-	/// TODO [Gav Wood] Please document me
+	/// Maximum allowed value.
 	pub max: Option<T>,
-	/// TODO [Gav Wood] Please document me
+	/// Value found.
 	pub found: T,
 }
 
@@ -29,11 +29,10 @@ pub struct OutOfBounds<T: fmt::Debug> {
 pub enum ExecutionError {
 	/// Returned when there gas paid for transaction execution is
 	/// lower than base gas required.
-	/// TODO [Gav Wood] Please document me
 	NotEnoughBaseGas { 
-		/// TODO [Gav Wood] Please document me
+		/// Absolute minimum gas required.
 		required: U256, 
-		/// TODO [Gav Wood] Please document me
+		/// Gas provided.
 		got: U256
 	},
 	/// Returned when block (gas_used + gas) > gas_limit.
@@ -41,26 +40,26 @@ pub enum ExecutionError {
 	/// If gas =< gas_limit, upstream may try to execute the transaction
 	/// in next block.
 	BlockGasLimitReached { 
-		/// TODO [Gav Wood] Please document me
+		/// Gas limit of block for transaction.
 		gas_limit: U256,
-		/// TODO [Gav Wood] Please document me
+		/// Gas used in block prior to transaction.
 		gas_used: U256,
-		/// TODO [Gav Wood] Please document me
+		/// Amount of gas in block.
 		gas: U256 
 	},
 	/// Returned when transaction nonce does not match state nonce.
 	InvalidNonce { 
-		/// TODO [Gav Wood] Please document me
+		/// Nonce expected.
 		expected: U256,
-		/// TODO [Gav Wood] Please document me
+		/// Nonce found.
 		got: U256
 	},
 	/// Returned when cost of transaction (value + gas_price * gas) exceeds 
 	/// current sender balance.
 	NotEnoughCash { 
-		/// TODO [Gav Wood] Please document me
+		/// Minimum required balance.
 		required: U512,
-		/// TODO [Gav Wood] Please document me
+		/// Actual balance.
 		got: U512
 	},
 	/// Returned when internal evm error occurs.
@@ -68,64 +67,68 @@ pub enum ExecutionError {
 }
 
 #[derive(Debug)]
-/// TODO [Gav Wood] Please document me
+/// Errors concerning transaction proessing.
 pub enum TransactionError {
-	/// TODO [Gav Wood] Please document me
+	/// Transaction's gas limit (aka gas) is invalid.
 	InvalidGasLimit(OutOfBounds<U256>),
 }
 
 #[derive(Debug, PartialEq, Eq)]
-/// TODO [arkpar] Please document me
+/// Errors concerning block processing.
 pub enum BlockError {
-	/// TODO [Gav Wood] Please document me
+	/// Block has too many uncles.
 	TooManyUncles(OutOfBounds<usize>),
-	/// TODO [Gav Wood] Please document me
-	UncleWrongGeneration,
-	/// TODO [Gav Wood] Please document me
+	/// Extra data is of an invalid length.
 	ExtraDataOutOfBounds(OutOfBounds<usize>),
-	/// TODO [arkpar] Please document me
+	/// Seal is incorrect format.
 	InvalidSealArity(Mismatch<usize>),
-	/// TODO [arkpar] Please document me
+	/// Block has too much gas used.
 	TooMuchGasUsed(OutOfBounds<U256>),
-	/// TODO [arkpar] Please document me
+	/// Uncles hash in header is invalid.
 	InvalidUnclesHash(Mismatch<H256>),
-	/// TODO [arkpar] Please document me
+	/// An uncle is from a generation too old.
 	UncleTooOld(OutOfBounds<BlockNumber>),
-	/// TODO [arkpar] Please document me
+	/// An uncle is from the same generation as the block.
 	UncleIsBrother(OutOfBounds<BlockNumber>),
-	/// TODO [arkpar] Please document me
+	/// An uncle is already in the chain.
 	UncleInChain(H256),
-	/// TODO [arkpar] Please document me
+	/// An uncle has a parent not in the chain.
 	UncleParentNotInChain(H256),
-	/// TODO [arkpar] Please document me
+	/// State root header field is invalid.
 	InvalidStateRoot(Mismatch<H256>),
-	/// TODO [arkpar] Please document me
+	/// Gas used header field is invalid.
 	InvalidGasUsed(Mismatch<U256>),
-	/// TODO [arkpar] Please document me
+	/// Transactions root header field is invalid.
 	InvalidTransactionsRoot(Mismatch<H256>),
-	/// TODO [arkpar] Please document me
+	/// Difficulty is out of range; this can be used as an looser error prior to getting a definitive
+	/// value for difficulty. This error needs only provide bounds of which it is out.
+	DifficultyOutOfBounds(OutOfBounds<U256>),
+	/// Difficulty header field is invalid; this is a strong error used after getting a definitive
+	/// value for difficulty (which is provided).
 	InvalidDifficulty(Mismatch<U256>),
-	/// TODO [arkpar] Please document me
+	/// Seal element of type H256 (max_hash for Ethash, but could be something else for
+	/// other seal engines) is out of bounds.
+	MismatchedH256SealElement(Mismatch<H256>),
+	/// Proof-of-work aspect of seal, which we assume is a 256-bit value, is invalid.
+	InvalidProofOfWork(OutOfBounds<U256>),
+	/// Gas limit header field is invalid.
 	InvalidGasLimit(OutOfBounds<U256>),
-	/// TODO [arkpar] Please document me
-	InvalidReceiptsStateRoot(Mismatch<H256>),
-	/// TODO [arkpar] Please document me
+	/// Receipts trie root header field is invalid.
+	InvalidReceiptsRoot(Mismatch<H256>),
+	/// Timestamp header field is invalid.
 	InvalidTimestamp(OutOfBounds<u64>),
-	/// TODO [arkpar] Please document me
+	/// Log bloom header field is invalid.
 	InvalidLogBloom(Mismatch<LogBloom>),
-	/// TODO [arkpar] Please document me
-	InvalidEthashDifficulty(Mismatch<U256>),
-	/// TODO [arkpar] Please document me
-	InvalidBlockNonce(Mismatch<H256>),
-	/// TODO [arkpar] Please document me
+	/// Parent hash field of header is invalid; this is an invalid error indicating a logic flaw in the codebase.
+	/// TODO: remove and favour an assert!/panic!.
 	InvalidParentHash(Mismatch<H256>),
-	/// TODO [arkpar] Please document me
+	/// Number field of header is invalid.
 	InvalidNumber(Mismatch<BlockNumber>),
 	/// Block number isn't sensible.
 	RidiculousNumber(OutOfBounds<BlockNumber>),
-	/// TODO [arkpar] Please document me
+	/// Parent given is unknown.
 	UnknownParent(H256),
-	/// TODO [Gav Wood] Please document me
+	/// Uncle parent given is unknown.
 	UnknownUncleParent(H256),
 }
 
@@ -154,15 +157,15 @@ pub type ImportResult = Result<H256, 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
+	/// Error concerning a utility.
 	Util(UtilError),
-	/// TODO [Gav Wood] Please document me
+	/// Error concerning block processing.
 	Block(BlockError),
-	/// TODO [Gav Wood] Please document me
+	/// Unknown engine given.
 	UnknownEngineName(String),
-	/// TODO [Gav Wood] Please document me
+	/// Error concerning EVM code execution.
 	Execution(ExecutionError),
-	/// TODO [Gav Wood] Please document me
+	/// Error concerning transaction processing.
 	Transaction(TransactionError),
 }
 
diff --git a/ethcore/src/ethereum/ethash.rs b/ethcore/src/ethereum/ethash.rs
index ce40c5f42..9cb0c5825 100644
--- a/ethcore/src/ethereum/ethash.rs
+++ b/ethcore/src/ethereum/ethash.rs
@@ -110,16 +110,18 @@ impl Engine for Ethash {
 		try!(UntrustedRlp::new(&header.seal[0]).as_val::<H256>());
 		try!(UntrustedRlp::new(&header.seal[1]).as_val::<H64>());
 
+		// TODO: consider removing these lines.
 		let min_difficulty = decode(self.spec().engine_params.get("minimumDifficulty").unwrap());
 		if header.difficulty < min_difficulty {
-			return Err(From::from(BlockError::InvalidDifficulty(Mismatch { expected: min_difficulty, found: header.difficulty })))
+			return Err(From::from(BlockError::DifficultyOutOfBounds(OutOfBounds { min: Some(min_difficulty), max: None, found: header.difficulty })))
 		}
+
 		let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(quick_get_difficulty(
 				&Ethash::to_ethash(header.bare_hash()), 
 				header.nonce().low_u64(),
 				&Ethash::to_ethash(header.mix_hash()))));
 		if difficulty < header.difficulty {
-			return Err(From::from(BlockError::InvalidEthashDifficulty(Mismatch { expected: header.difficulty, found: difficulty })));
+			return Err(From::from(BlockError::InvalidProofOfWork(OutOfBounds { min: Some(header.difficulty), max: None, found: difficulty })));
 		}
 		Ok(())
 	}
@@ -129,10 +131,10 @@ impl Engine for Ethash {
 		let mix = Ethash::from_ethash(result.mix_hash);
 		let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(result.value));
 		if mix != header.mix_hash() {
-			return Err(From::from(BlockError::InvalidBlockNonce(Mismatch { expected: mix, found: header.mix_hash() })));
+			return Err(From::from(BlockError::MismatchedH256SealElement(Mismatch { expected: mix, found: header.mix_hash() })));
 		}
 		if difficulty < header.difficulty {
-			return Err(From::from(BlockError::InvalidEthashDifficulty(Mismatch { expected: header.difficulty, found: difficulty })));
+			return Err(From::from(BlockError::InvalidProofOfWork(OutOfBounds { min: Some(header.difficulty), max: None, found: difficulty })));
 		}
 		Ok(())
 	}
diff --git a/ethcore/src/ethereum/mod.rs b/ethcore/src/ethereum/mod.rs
index c32fc40c6..ec6cfe103 100644
--- a/ethcore/src/ethereum/mod.rs
+++ b/ethcore/src/ethereum/mod.rs
@@ -3,9 +3,9 @@
 //! Contains all Ethereum network specific stuff, such as denominations and
 //! consensus specifications.
 
-/// TODO [Gav Wood] Please document me
+/// Export the ethash module.
 pub mod ethash;
-/// TODO [Gav Wood] Please document me
+/// Export the denominations module.
 pub mod denominations;
 
 pub use self::ethash::*;
diff --git a/ethcore/src/extras.rs b/ethcore/src/extras.rs
index be5121a2d..f3f3208ad 100644
--- a/ethcore/src/extras.rs
+++ b/ethcore/src/extras.rs
@@ -68,9 +68,9 @@ impl ExtrasReadable for DB {
 
 /// Implementations should convert arbitrary type to database key slice
 pub trait ExtrasSliceConvertable {
-	/// TODO [Gav Wood] Please document me
+	/// Convert self, with `i` (the index), to a 264-bit extras DB key.
 	fn to_extras_slice(&self, i: ExtrasIndex) -> H264;
-	/// TODO [debris] Please document me
+	/// Interpret self as a 256-bit hash, if natively `H256`.
 	fn as_h256(&self) -> Option<&H256> { None }
 }
 
diff --git a/ethcore/src/header.rs b/ethcore/src/header.rs
index 69dba5ec8..b188a6bcf 100644
--- a/ethcore/src/header.rs
+++ b/ethcore/src/header.rs
@@ -48,9 +48,9 @@ pub struct Header {
 	/// Block seal.
 	pub seal: Vec<Bytes>,
 
-	/// TODO [arkpar] Please document me
+	/// The memoized hash of the RLP representation *including* the seal fields.
 	pub hash: RefCell<Option<H256>>,
-	/// TODO [Gav Wood] Please document me
+	/// The memoized hash of the RLP representation *without* the seal fields.
 	pub bare_hash: RefCell<Option<H256>>,
 }
 
@@ -86,50 +86,50 @@ impl Header {
 		Self::default()
 	}
 
-	/// TODO [Gav Wood] Please document me
+	/// Get the number field of the header.
 	pub fn number(&self) -> BlockNumber { self.number }
-	/// TODO [Gav Wood] Please document me
+	/// Get the timestamp field of the header.
 	pub fn timestamp(&self) -> u64 { self.timestamp }
-	/// TODO [Gav Wood] Please document me
+	/// Get the author field of the header.
 	pub fn author(&self) -> &Address { &self.author }
 
-	/// TODO [Gav Wood] Please document me
+	/// Get the extra data field of the header.
 	pub fn extra_data(&self) -> &Bytes { &self.extra_data }
 
-	/// TODO [Gav Wood] Please document me
+	/// Get the state root field of the header.
 	pub fn state_root(&self) -> &H256 { &self.state_root }
-	/// TODO [Gav Wood] Please document me
+	/// Get the receipts root field of the header.
 	pub fn receipts_root(&self) -> &H256 { &self.receipts_root }
-	/// TODO [Gav Wood] Please document me
+	/// Get the gas limit field of the header.
 	pub fn gas_limit(&self) -> &U256 { &self.gas_limit }
 
-	/// TODO [Gav Wood] Please document me
+	/// Get the difficulty field of the header.
 	pub fn difficulty(&self) -> &U256 { &self.difficulty }
-	/// TODO [Gav Wood] Please document me
+	/// Get the seal field of the header.
 	pub fn seal(&self) -> &Vec<Bytes> { &self.seal }
 
 	// TODO: seal_at, set_seal_at &c.
 
-	/// TODO [Gav Wood] Please document me
+	/// Set the number field of the header.
 	pub fn set_number(&mut self, a: BlockNumber) { self.number = a; self.note_dirty(); }
-	/// TODO [Gav Wood] Please document me
+	/// Set the timestamp field of the header.
 	pub fn set_timestamp(&mut self, a: u64) { self.timestamp = a; self.note_dirty(); }
-	/// TODO [Gav Wood] Please document me
+	/// Set the timestamp field of the header to the current time.
 	pub fn set_timestamp_now(&mut self) { self.timestamp = now_utc().to_timespec().sec as u64; self.note_dirty(); }
-	/// TODO [Gav Wood] Please document me
+	/// Set the author field of the header.
 	pub fn set_author(&mut self, a: Address) { if a != self.author { self.author = a; self.note_dirty(); } }
 
-	/// TODO [Gav Wood] Please document me
+	/// Set the extra data field of the header.
 	pub fn set_extra_data(&mut self, a: Bytes) { if a != self.extra_data { self.extra_data = a; self.note_dirty(); } }
 
-	/// TODO [Gav Wood] Please document me
+	/// Set the gas used field of the header.
 	pub fn set_gas_used(&mut self, a: U256) { self.gas_used = a; self.note_dirty(); }
-	/// TODO [Gav Wood] Please document me
+	/// Set the gas limit field of the header.
 	pub fn set_gas_limit(&mut self, a: U256) { self.gas_limit = a; self.note_dirty(); }
 
-	/// TODO [Gav Wood] Please document me
+	/// Set the difficulty field of the header.
 	pub fn set_difficulty(&mut self, a: U256) { self.difficulty = a; self.note_dirty(); }
-	/// TODO [Gav Wood] Please document me
+	/// Set the seal field of the header.
 	pub fn set_seal(&mut self, a: Vec<Bytes>) { self.seal = a; self.note_dirty(); }
 
 	/// Get the hash of this header (sha3 of the RLP).
@@ -163,7 +163,7 @@ impl Header {
 	}
 
 	// TODO: make these functions traity 
-	/// TODO [Gav Wood] Please document me
+	/// Place this header into an RLP stream `s`, optionally `with_seal`.
 	pub fn stream_rlp(&self, s: &mut RlpStream, with_seal: Seal) {
 		s.begin_list(13 + match with_seal { Seal::With => self.seal.len(), _ => 0 });
 		s.append(&self.parent_hash);
@@ -186,14 +186,14 @@ impl Header {
 		}
 	}
 
-	/// TODO [Gav Wood] Please document me
+	/// Get the RLP of this header, optionally `with_seal`.
 	pub fn rlp(&self, with_seal: Seal) -> Bytes {
 		let mut s = RlpStream::new();
 		self.stream_rlp(&mut s, with_seal);
 		s.out()
 	}
 
-	/// TODO [debris] Please document me
+	/// Get the SHA3 (Keccak) of this header, optionally `with_seal`.
 	pub fn rlp_sha3(&self, with_seal: Seal) -> H256 { self.rlp(with_seal).sha3() }
 }
 
diff --git a/ethcore/src/json_tests/chain.rs b/ethcore/src/json_tests/chain.rs
index 19e792f52..6ee7e9f9e 100644
--- a/ethcore/src/json_tests/chain.rs
+++ b/ethcore/src/json_tests/chain.rs
@@ -15,12 +15,12 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec<String> {
 		{
 			let mut fail_unless = |cond: bool| if !cond && !fail {
 				failed.push(name.clone());
-				flush(format!("FAIL\n"));
+				flushln!("FAIL");
 				fail = true;
 				true
 			} else {false};
 
-			flush(format!("   - {}...", name));
+			flush!("   - {}...", name);
 
 			let blocks: Vec<(Bytes, bool)> = test["blocks"].as_array().unwrap().iter().map(|e| (xjson!(&e["rlp"]), e.find("blockHeader").is_some())).collect();
 			let mut spec = match era {
@@ -50,7 +50,7 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec<String> {
 			}
 		}
 		if !fail {
-			flush(format!("ok\n"));
+			flushln!("ok");
 		}
 	}
 	println!("!!! {:?} tests from failed.", failed.len());
diff --git a/ethcore/src/json_tests/state.rs b/ethcore/src/json_tests/state.rs
index 3fb43c132..fa8da9329 100644
--- a/ethcore/src/json_tests/state.rs
+++ b/ethcore/src/json_tests/state.rs
@@ -19,19 +19,19 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec<String> {
 		ChainEra::Homestead => ethereum::new_homestead_test(),
 	}.to_engine().unwrap();
 
-	flush(format!("\n"));
+	flushln!("");
 
 	for (name, test) in json.as_object().unwrap() {
 		let mut fail = false;
 		{
 			let mut fail_unless = |cond: bool| if !cond && !fail {
 				failed.push(name.clone());
-				flush(format!("FAIL\n"));
+				flushln!("FAIL");
 				fail = true;
 				true
 			} else {false};
 
-			flush(format!("   - {}...", name));
+			flush!("   - {}...", name);
 
 			let t = Transaction::from_json(&test["transaction"]);
 			let env = EnvInfo::from_json(&test["env"]);
@@ -73,7 +73,7 @@ pub fn json_chain_test(json_data: &[u8], era: ChainEra) -> Vec<String> {
 			}
 		}
 		if !fail {
-			flush(format!("ok\n"));
+			flushln!("ok");
 		}
 		// TODO: Add extra APIs for output
 		//if fail_unless(out == r.)
diff --git a/ethcore/src/log_entry.rs b/ethcore/src/log_entry.rs
index 165c6985e..46faad797 100644
--- a/ethcore/src/log_entry.rs
+++ b/ethcore/src/log_entry.rs
@@ -1,14 +1,14 @@
 use util::*;
 use basic_types::LogBloom;
 
-/// A single log's entry.
+/// A record of execution for a `LOG` operation.
 #[derive(Default, Debug, Clone, PartialEq, Eq)]
 pub struct LogEntry {
-	/// TODO [Gav Wood] Please document me
+	/// The address of the contract executing at the point of the `LOG` operation.
 	pub address: Address,
-	/// TODO [Gav Wood] Please document me
+	/// The topics associated with the `LOG` operation.
 	pub topics: Vec<H256>,
-	/// TODO [Gav Wood] Please document me
+	/// The data associated with the `LOG` operation.
 	pub data: Bytes,
 }
 
diff --git a/ethcore/src/pod_account.rs b/ethcore/src/pod_account.rs
index 76127b89a..7bc886617 100644
--- a/ethcore/src/pod_account.rs
+++ b/ethcore/src/pod_account.rs
@@ -2,15 +2,16 @@ use util::*;
 use account::*;
 
 #[derive(Debug,Clone,PartialEq,Eq)]
-/// Genesis account data. Does not have a DB overlay cache.
+/// An account, expressed as Plain-Old-Data (hence the name).
+/// Does not have a DB overlay cache, code hash or anything like that.
 pub struct PodAccount {
-	/// TODO [Gav Wood] Please document me
+	/// The balance of the account.
 	pub balance: U256,
-	/// TODO [Gav Wood] Please document me
+	/// The nonce of the account.
 	pub nonce: U256,
-	/// TODO [Gav Wood] Please document me
+	/// The code of the account.
 	pub code: Bytes,
-	/// TODO [Gav Wood] Please document me
+	/// The storage of the account.
 	pub storage: BTreeMap<H256, H256>,
 }
 
diff --git a/ethcore/src/pod_state.rs b/ethcore/src/pod_state.rs
index 22969f36b..b373171ad 100644
--- a/ethcore/src/pod_state.rs
+++ b/ethcore/src/pod_state.rs
@@ -2,7 +2,7 @@ use util::*;
 use pod_account::*;
 
 #[derive(Debug,Clone,PartialEq,Eq,Default)]
-/// TODO [Gav Wood] Please document me
+/// State of all accounts in the system expressed in Plain Old Data.
 pub struct PodState (BTreeMap<Address, PodAccount>);
 
 impl PodState {
diff --git a/ethcore/src/receipt.rs b/ethcore/src/receipt.rs
index b12cbab23..43f674aa9 100644
--- a/ethcore/src/receipt.rs
+++ b/ethcore/src/receipt.rs
@@ -5,18 +5,18 @@ use log_entry::LogEntry;
 /// Information describing execution of a transaction.
 #[derive(Default, Debug, Clone)]
 pub struct Receipt {
-	/// TODO [Gav Wood] Please document me
+	/// The state root after executing the transaction.
 	pub state_root: H256,
-	/// TODO [Gav Wood] Please document me
+	/// The total gas used in the block following execution of the transaction.
 	pub gas_used: U256,
-	/// TODO [Gav Wood] Please document me
+	/// The OR-wide combination of all logs' blooms for this transaction.
 	pub log_bloom: LogBloom,
-	/// TODO [Gav Wood] Please document me
+	/// The logs stemming from this transaction.
 	pub logs: Vec<LogEntry>,
 }
 
 impl Receipt {
-	/// TODO [Gav Wood] Please document me
+	/// Create a new receipt.
 	pub fn new(state_root: H256, gas_used: U256, logs: Vec<LogEntry>) -> Receipt {
 		Receipt {
 			state_root: state_root,
diff --git a/ethcore/src/spec.rs b/ethcore/src/spec.rs
index 7cb251096..50bbbb633 100644
--- a/ethcore/src/spec.rs
+++ b/ethcore/src/spec.rs
@@ -34,53 +34,50 @@ fn json_to_rlp_map(json: &Json) -> HashMap<String, Bytes> {
 /// chain and those to be interpreted by the active chain engine.
 #[derive(Debug)]
 pub struct Spec {
-	// User friendly spec name
-	/// TODO [Gav Wood] Please document me
+	/// User friendly spec name
 	pub name: String,
-	// What engine are we using for this?
-	/// TODO [Gav Wood] Please document me
+	/// What engine are we using for this?
 	pub engine_name: String,
 
 	/// Known nodes on the network in enode format.
 	pub nodes: Vec<String>,
 
-	// Parameters concerning operation of the specific engine we're using.
-	// Name -> RLP-encoded value
-	/// TODO [Gav Wood] Please document me
+	/// Parameters concerning operation of the specific engine we're using.
+	/// Maps the parameter name to an RLP-encoded value.
 	pub engine_params: HashMap<String, Bytes>,
 
-	// Builtin-contracts are here for now but would like to abstract into Engine API eventually.
-	/// TODO [Gav Wood] Please document me
+	/// Builtin-contracts we would like to see in the chain.
+	/// (In principle these are just hints for the engine since that has the last word on them.)
 	pub builtins: BTreeMap<Address, Builtin>,
 
-	// Genesis params.
-	/// TODO [Gav Wood] Please document me
+	/// The genesis block's parent hash field.
 	pub parent_hash: H256,
-	/// TODO [Gav Wood] Please document me
+	/// The genesis block's author field.
 	pub author: Address,
-	/// TODO [Gav Wood] Please document me
+	/// The genesis block's difficulty field.
 	pub difficulty: U256,
-	/// TODO [Gav Wood] Please document me
+	/// The genesis block's gas limit field.
 	pub gas_limit: U256,
-	/// TODO [Gav Wood] Please document me
+	/// The genesis block's gas used field.
 	pub gas_used: U256,
-	/// TODO [Gav Wood] Please document me
+	/// The genesis block's timestamp field.
 	pub timestamp: u64,
 	/// Transactions root of the genesis block. Should be SHA3_NULL_RLP.
 	pub transactions_root: H256,
 	/// Receipts root of the genesis block. Should be SHA3_NULL_RLP.
 	pub receipts_root: H256,
-	/// TODO [arkpar] Please document me
+	/// The genesis block's extra data field.
 	pub extra_data: Bytes,
-	/// TODO [Gav Wood] Please document me
-	genesis_state: PodState,
-	/// TODO [Gav Wood] Please document me
+	/// The number of seal fields in the genesis block.
 	pub seal_fields: usize,
-	/// TODO [Gav Wood] Please document me
+	/// Each seal field, expressed as RLP, concatenated.
 	pub seal_rlp: Bytes,
 
 	// May be prepopulated if we know this in advance.
 	state_root_memo: RwLock<Option<H256>>,
+
+	// Genesis state as plain old data.
+	genesis_state: PodState,
 }
 
 #[allow(wrong_self_convention)] // because to_engine(self) should be to_engine(&self)
@@ -106,7 +103,7 @@ impl Spec {
 	/// Get the known knodes of the network in enode format.
 	pub fn nodes(&self) -> &Vec<String> { &self.nodes }
 
-	/// TODO [Gav Wood] Please document me
+	/// Get the header of the genesis block.
 	pub fn genesis_header(&self) -> Header {
 		Header {
 			parent_hash: self.parent_hash.clone(),
diff --git a/ethcore/src/state.rs b/ethcore/src/state.rs
index fb336f3bb..3c12804b9 100644
--- a/ethcore/src/state.rs
+++ b/ethcore/src/state.rs
@@ -5,7 +5,7 @@ use pod_account::*;
 use pod_state::PodState;
 //use state_diff::*;	// TODO: uncomment once to_pod() works correctly.
 
-/// TODO [Gav Wood] Please document me
+/// Result type for the execution ("application") of a transaction.
 pub type ApplyResult = Result<Receipt, Error>;
 
 /// Representation of the entire state of all accounts in the system.
diff --git a/ethcore/src/state_diff.rs b/ethcore/src/state_diff.rs
index 12e2d76ca..1caa62ef1 100644
--- a/ethcore/src/state_diff.rs
+++ b/ethcore/src/state_diff.rs
@@ -3,7 +3,8 @@ use pod_state::*;
 use account_diff::*;
 
 #[derive(Debug,Clone,PartialEq,Eq)]
-/// TODO [Gav Wood] Please document me
+/// Expression for the delta between two system states. Encoded the 
+/// delta of every altered account.
 pub struct StateDiff (BTreeMap<Address, AccountDiff>);
 
 impl StateDiff {
diff --git a/ethcore/src/substate.rs b/ethcore/src/substate.rs
index 182cef93b..a5c353351 100644
--- a/ethcore/src/substate.rs
+++ b/ethcore/src/substate.rs
@@ -26,7 +26,7 @@ impl Substate {
 		}
 	}
 
-	/// TODO [Gav Wood] Please document me
+	/// Merge secondary substate `s` into self, accruing each element correspondingly.
 	pub fn accrue(&mut self, s: Substate) {
 		self.suicides.extend(s.suicides.into_iter());
 		self.logs.extend(s.logs.into_iter());
diff --git a/ethcore/src/transaction.rs b/ethcore/src/transaction.rs
index d71506672..bc777d7ae 100644
--- a/ethcore/src/transaction.rs
+++ b/ethcore/src/transaction.rs
@@ -36,11 +36,11 @@ pub struct Transaction {
 	pub data: Bytes,
 
 	// signature
-	/// TODO [Gav Wood] Please document me
+	/// The V field of the signature, either 27 or 28; helps describe the point on the curve.
 	pub v: u8,
-	/// TODO [Gav Wood] Please document me
+	/// The R field of the signature; helps describe the point on the curve.
 	pub r: U256,
-	/// TODO [debris] Please document me
+	/// The S field of the signature; helps describe the point on the curve.
 	pub s: U256,
 
 	hash: RefCell<Option<H256>>,
@@ -48,7 +48,7 @@ pub struct Transaction {
 }
 
 impl Transaction {
-	/// TODO [Gav Wood] Please document me
+	/// Create a new transaction.
 	#[cfg(test)]
 	pub fn new() -> Self {
 		Transaction {
diff --git a/ethcore/src/verification.rs b/ethcore/src/verification.rs
index 020f1b40f..efed43b84 100644
--- a/ethcore/src/verification.rs
+++ b/ethcore/src/verification.rs
@@ -154,7 +154,7 @@ pub fn verify_block_final(expected: &Header, got: &Header) -> Result<(), Error>
 		return Err(From::from(BlockError::InvalidStateRoot(Mismatch { expected: expected.state_root.clone(), found: got.state_root.clone() })))
 	}
 	if expected.receipts_root != got.receipts_root {
-		return Err(From::from(BlockError::InvalidReceiptsStateRoot(Mismatch { expected: expected.receipts_root.clone(), found: got.receipts_root.clone() })))
+		return Err(From::from(BlockError::InvalidReceiptsRoot(Mismatch { expected: expected.receipts_root.clone(), found: got.receipts_root.clone() })))
 	}
 	Ok(())
 }
diff --git a/util/src/bytes.rs b/util/src/bytes.rs
index 050c07a66..f4937cafc 100644
--- a/util/src/bytes.rs
+++ b/util/src/bytes.rs
@@ -83,11 +83,12 @@ impl<'a> fmt::Display for PrettySlice<'a> {
 	}
 }
 
-/// TODO [Gav Wood] Please document me
+/// Trait to allow a type to be pretty-printed in `format!`, where unoverridable
+/// defaults cannot otherwise be avoided.
 pub trait ToPretty {
-	/// TODO [Gav Wood] Please document me
+	/// Convert a type into a derivative form in order to make `format!` print it prettily.
 	fn pretty(&self) -> PrettySlice;
-	/// TODO [Gav Wood] Please document me
+	/// Express the object as a hex string.
 	fn to_hex(&self) -> String {
 		format!("{}", self.pretty())
 	}
@@ -144,11 +145,12 @@ pub type Bytes = Vec<u8>;
 /// Slice of bytes to underlying memory
 pub trait BytesConvertable {
 	// TODO: rename to as_slice
-	/// TODO [Gav Wood] Please document me
+	/// Get the underlying byte-wise representation of the value.
+	/// Deprecated - use `as_slice` instead.
 	fn bytes(&self) -> &[u8];
-	/// TODO [Gav Wood] Please document me
+	/// Get the underlying byte-wise representation of the value.
 	fn as_slice(&self) -> &[u8] { self.bytes() }
-	/// TODO [Gav Wood] Please document me
+	/// Get a copy of the underlying byte-wise representation.
 	fn to_bytes(&self) -> Bytes { self.as_slice().to_vec() }
 }
 
diff --git a/util/src/common.rs b/util/src/common.rs
index 9cf7a3765..bfc883a6b 100644
--- a/util/src/common.rs
+++ b/util/src/common.rs
@@ -48,7 +48,7 @@ macro_rules! flushln {
 	($fmt:expr, $($arg:tt)*) => (flush!(concat!($fmt, "\n"), $($arg)*));
 }
 
-/// TODO [Gav Wood] Please document me
+#[doc(hidden)]
 pub fn flush(s: String) {
 	::std::io::stdout().write(s.as_bytes()).unwrap();
 	::std::io::stdout().flush().unwrap();
diff --git a/util/src/trie/triedbmut.rs b/util/src/trie/triedbmut.rs
index 4c3d36646..e4e572609 100644
--- a/util/src/trie/triedbmut.rs
+++ b/util/src/trie/triedbmut.rs
@@ -72,7 +72,7 @@ impl<'db> TrieDBMut<'db> {
 	// TODO: return Result<Self, TrieError>
 	pub fn from_existing(db: &'db mut HashDB, root: &'db mut H256) -> Self {
 		if !db.exists(root) {
-			flush(format!("Trie root not found {}", root));
+			flushln!("Trie root not found {}", root);
 			panic!("Trie root not found!");
 		}
 		TrieDBMut {