Merge pull request #309 from ethcore/doceffort

Document some stuff.

README.md

@@ -7,10 +7,9 @@
 [coveralls-image]: https://coveralls.io/repos/github/ethcore/parity/badge.svg?branch=master&t=Fk0OuQ
 [coveralls-url]: https://coveralls.io/r/ethcore/parity?branch=master
 
-
 ### Building from source
 
-##### Ubuntu 14.04 and later
+##### Ubuntu 14.04
 
 ```bash
 # install rocksdb
@@ -22,10 +21,8 @@ apt-get install -y --force-yes librocksdb
 curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sh -s -- --yes
 
 # install nightly and make it default
-multirust update nightly && multirust default nightly
-
-# export rust LIBRARY_PATH
-export LIBRARY_PATH=/usr/local/lib
+multirust update nightly
+multirust default nightly
 
 # download and build parity
 git clone https://github.com/ethcore/parity
@@ -33,7 +30,31 @@ cd parity
 cargo build --release
 ```
 
-##### OSX
+##### Linux
+
+```bash
+# install rocksdb
+git clone --tag v4.1 --depth=1 https://github.com/facebook/rocksdb.git
+cd rocksdb
+make shared_lib 
+sudo cp -a librocksdb.so* /usr/lib 
+sudo ldconfig 
+cd ..
+
+# install rust nightly
+curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sudo sh -s -- --yes
+
+# install nightly and make it default
+sudo multirust update nightly
+sudo multirust default nightly
+
+# download and build parity
+git clone https://github.com/ethcore/parity
+cd parity
+cargo build --release
+```
+
+##### OSX with Homebrew
 
 ```bash
 # install rocksdb && multirust
@@ -44,9 +65,6 @@ brew install multirust
 # install nightly and make it default
 multirust update nightly && multirust default nightly
 
-# export rust LIBRARY_PATH
-export LIBRARY_PATH=/usr/local/lib
-
 # download and build parity
 git clone https://github.com/ethcore/parity
 cd parity

ethcore/src/account_diff.rs

@@ -7,11 +7,11 @@ use pod_account::*;
 /// Change in existance type. 
 // TODO: include other types of change.
 pub enum Existance {
-	/// TODO [Gav Wood] Please document me
+	/// Item came into existance.
 	Born,
-	/// TODO [Gav Wood] Please document me
+	/// Item stayed in existance.
 	Alive,
-	/// TODO [Gav Wood] Please document me
+	/// Item went out of existance.
 	Died,
 }
 
@@ -27,20 +27,20 @@ impl fmt::Display for Existance {
 }
 
 #[derive(Debug,Clone,PartialEq,Eq)]
-/// TODO [Gav Wood] Please document me
+/// Account diff.
 pub struct AccountDiff {
-	/// TODO [Gav Wood] Please document me
-	pub balance: Diff<U256>,				// Allowed to be Same
-	/// TODO [Gav Wood] Please document me
+	/// Change in balance, allowed to be `Diff::Same`.
+	pub balance: Diff<U256>,
+	/// Change in nonce, allowed to be `Diff::Same`.
 	pub nonce: Diff<U256>,					// Allowed to be Same
-	/// TODO [Gav Wood] Please document me
+	/// Change in code, allowed to be `Diff::Same`.
 	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
+	/// Change in storage, values are not allowed to be `Diff::Same`.
+	pub storage: BTreeMap<H256, Diff<H256>>,
 }
 
 impl AccountDiff {
-	/// TODO [Gav Wood] Please document me
+	/// Get `Existance` projection.
 	pub fn existance(&self) -> Existance {
 		match self.balance {
 			Diff::Born(_) => Existance::Born,
@@ -49,7 +49,8 @@ impl AccountDiff {
 		}
 	}
 
-	/// TODO [Gav Wood] Please document me
+	/// Determine difference between two optionally existance `Account`s. Returns None
+	/// if they are the same.
 	pub fn diff_pod(pre: Option<&PodAccount>, post: Option<&PodAccount>) -> Option<AccountDiff> {
 		match (pre, post) {
 			(None, Some(x)) => Some(AccountDiff {

ethcore/src/basic_types.rs

@@ -8,10 +8,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
+/// Semantic boolean for when a seal/signature is included.
 pub enum Seal {
-	/// TODO [Gav Wood] Please document me
+	/// The seal/signature is included.
 	With,
-	/// TODO [Gav Wood] Please document me
+	/// The seal/signature is not included.
 	Without,
 }

ethcore/src/builtin.rs

@@ -63,7 +63,8 @@ impl Builtin {
 	}
 }
 
-/// TODO [Gav Wood] Please document me
+/// Copy a bunch of bytes to a destination; if the `src` is too small to fill `dest`,
+/// leave the rest unchanged.
 pub fn copy_to(src: &[u8], dest: &mut[u8]) {
 	// NICE: optimise
 	for i in 0..min(src.len(), dest.len()) {

ethcore/src/client.rs

@@ -116,18 +116,18 @@ pub trait BlockChainClient : Sync + Send {
 }
 
 #[derive(Default, Clone, Debug, Eq, PartialEq)]
-/// TODO [Gav Wood] Please document me
+/// Report on the status of a client.
 pub struct ClientReport {
-	/// TODO [Gav Wood] Please document me
+	/// How many blocks have been imported so far.
 	pub blocks_imported: usize,
-	/// TODO [Gav Wood] Please document me
+	/// How many transactions have been applied so far.
 	pub transactions_applied: usize,
-	/// TODO [Gav Wood] Please document me
+	/// How much gas has been processed so far.
 	pub gas_processed: U256,
 }
 
 impl ClientReport {
-	/// TODO [Gav Wood] Please document me
+	/// Alter internal reporting to reflect the additional `block` has been processed.
 	pub fn accrue_block(&mut self, block: &PreVerifiedBlock) {
 		self.blocks_imported += 1;
 		self.transactions_applied += block.transactions.len();

ethcore/src/engine.rs

@@ -31,17 +31,16 @@ 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
+	/// Maximum number of uncles a block is allowed to declare.
 	fn maximum_uncle_count(&self) -> usize { 2 }
-	/// TODO [Gav Wood] Please document me
+	/// The nonce with which accounts begin.
 	fn account_start_nonce(&self) -> U256 { decode(&self.spec().engine_params.get("accountStartNonce").unwrap()) }
 
-	/// Block transformation functions, before and after the transactions.
+	/// Block transformation functions, before the transactions.
 	fn on_new_block(&self, _block: &mut ExecutedBlock) {}
-	/// TODO [Gav Wood] Please document me
+	/// Block transformation functions, after the transactions.
 	fn on_close_block(&self, _block: &mut ExecutedBlock) {}
 
-	// TODO: consider including State in the params for verification functions.
 	/// Phase 1 quick block verification. Only does checks that are cheap. `block` (the header's full block) 
 	/// may be provided for additional checks. Returns either a null `Ok` or a general error detailing the problem with import.
 	fn verify_block_basic(&self, _header: &Header,  _block: Option<&[u8]>) -> Result<(), Error> { Ok(()) }
@@ -58,7 +57,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
+	/// Verify a particular transaction is valid.
 	fn verify_transaction(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) }
 
 	/// Don't forget to call Super::populateFromParent when subclassing & overriding.
@@ -67,11 +66,13 @@ 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
+	/// Determine whether a particular address is a builtin contract.
 	fn is_builtin(&self, a: &Address) -> bool { self.spec().builtins.contains_key(a) }
-	/// TODO [Gav Wood] Please document me
+	/// Determine the code execution cost of the builtin contract with address `a`.
+	/// Panics if `is_builtin(a)` is not true.
 	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
+	/// Execution the builtin contract `a` on `input` and return `output`.
+	/// Panics if `is_builtin(a)` is not true.
 	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.