Merge pull request #301 from ethcore/ethcore_docs

ethcore docs

ethcore/src/account.rs

@@ -1,3 +1,5 @@
+//! Single account in the system.
+
 use util::*;
 use pod_account::*;
 

ethcore/src/account_diff.rs

@@ -1,3 +1,5 @@
+//! Diff between two accounts.
+
 use util::*;
 use pod_account::*;
 

ethcore/src/basic_types.rs

@@ -1,3 +1,5 @@
+//! Ethcore basic typenames.
+
 use util::*;
 
 /// Type for a 2048-bit log-bloom, as used by our blocks.

ethcore/src/block.rs

@@ -1,3 +1,5 @@
+//! Blockchain block.
+
 #![allow(ptr_arg)] // Because of &LastHashes -> &Vec<_>
 
 use common::*;
@@ -18,7 +20,7 @@ pub struct Block {
 }
 
 impl Block {
-	/// Returns true iff the given bytes form a valid encoding of a block in RLP.
+	/// Returns true if the given bytes form a valid encoding of a block in RLP.
 	// TODO: implement Decoder for this and have this use that.
 	pub fn is_good(b: &[u8]) -> bool {
 		/*
@@ -71,16 +73,15 @@ pub struct ExecutedBlock {
 
 /// A set of references to `ExecutedBlock` fields that are publicly accessible. 
 pub struct BlockRefMut<'a> {
-	/// TODO [Gav Wood] Please document me
+	/// Block header.
 	pub header: &'a Header,
-	/// TODO [Gav Wood] Please document me
+	/// Block transactions.
 	pub transactions: &'a Vec<Transaction>,
-	/// TODO [Gav Wood] Please document me
+	/// Block uncles.
 	pub uncles: &'a Vec<Header>,
-
+	/// Transaction receipts.
-	/// TODO [Gav Wood] Please document me
 	pub receipts: &'a Vec<Receipt>,
-	/// TODO [Gav Wood] Please document me
+	/// State.
 	pub state: &'a mut State,
 }
 
@@ -394,4 +395,4 @@ mod tests {
 		assert_eq!(orig_db.keys(), db.keys());
 		assert!(orig_db.keys().iter().filter(|k| orig_db.get(k.0) != db.get(k.0)).next() == None);
 	}
-}
+}

ethcore/src/blockchain.rs

@@ -1,4 +1,4 @@
-//! Fast access to blockchain data.
+//! Blockchain database.
 
 use util::*;
 use rocksdb::{DB, WriteBatch, Writable};
@@ -8,33 +8,27 @@ use transaction::*;
 use views::*;
 
 /// Represents a tree route between `from` block and `to` block:
-///
-/// - `blocks` - a vector of hashes of all blocks, ordered from `from` to `to`.
-///
-/// - `ancestor` - best common ancestor of these blocks.
-///
-/// - `index` - an index where best common ancestor would be.
 pub struct TreeRoute {
-	/// TODO [debris] Please document me
+	/// A vector of hashes of all blocks, ordered from `from` to `to`.
 	pub blocks: Vec<H256>,
-	/// TODO [debris] Please document me
+	/// Best common ancestor of these blocks.
 	pub ancestor: H256,
-	/// TODO [debris] Please document me
+	/// An index where best common ancestor would be.
 	pub index: usize
 }
 
 /// Represents blockchain's in-memory cache size in bytes.
 #[derive(Debug)]
 pub struct CacheSize {
-	/// TODO [debris] Please document me
+	/// Blocks cache size.
 	pub blocks: usize,
-	/// TODO [debris] Please document me
+	/// BlockDetails cache size.
 	pub block_details: usize,
-	/// TODO [debris] Please document me
+	/// Transaction addresses cache size.
 	pub transaction_addresses: usize,
-	/// TODO [debris] Please document me
+	/// Logs cache size.
 	pub block_logs: usize,
-	/// TODO [debris] Please document me
+	/// Blooms cache size.
 	pub blocks_blooms: usize
 }
 

ethcore/src/client.rs

@@ -1,3 +1,5 @@
+//! Blockchain database client.
+
 use util::*;
 use rocksdb::{Options, DB};
 use blockchain::{BlockChain, BlockProvider, CacheSize};

ethcore/src/evm/evm.rs

@@ -44,6 +44,7 @@ pub enum Error {
 	},
 	/// Returned on evm internal error. Should never be ignored during development.
 	/// Likely to cause consensus issues.
+	#[allow(dead_code)] // created only by jit
 	Internal,
 }
 

ethcore/src/evm/factory.rs

@@ -1,4 +1,6 @@
 //! Evm factory.
+//!
+//! TODO: consider spliting it into two separate files.
 use std::fmt;
 use evm::Evm;
 
@@ -6,6 +8,7 @@ use evm::Evm;
 /// TODO [Tomusdrw] Please document me
 pub enum VMType {
 	/// TODO [Tomusdrw] Please document me
+	#[allow(dead_code)] // crated only by jit
 	Jit,
 	/// TODO [Tomusdrw] Please document me
 	Interpreter
@@ -20,6 +23,7 @@ impl fmt::Display for VMType {
 	}
 }
 
+#[cfg(test)]
 impl VMType {
 	/// Return all possible VMs (JIT, Interpreter)
 	#[cfg(feature="jit")]
@@ -53,6 +57,7 @@ impl Factory {
 	}
 
 	/// Create new instance of specific `VMType` factory
+	#[cfg(test)]
 	pub fn new(evm: VMType) -> Factory {
 		Factory {
 			evm: evm

ethcore/src/executive.rs

@@ -129,7 +129,7 @@ impl<'a> Executive<'a> {
 
 		let mut substate = Substate::new();
 
-		let res = match *t.action() {
+		let res = match t.action {
 			Action::Create => {
 				let new_address = contract_address(&sender, &nonce);
 				let params = ActionParams {

ethcore/src/extras.rs

@@ -1,3 +1,5 @@
+//! Blockchain DB extras.
+
 use util::*;
 use header::BlockNumber;
 use rocksdb::{DB, Writable};

ethcore/src/header.rs

@@ -1,3 +1,5 @@
+//! Block header.
+
 use util::*;
 use basic_types::*;
 use time::now_utc;

ethcore/src/lib.rs

@@ -2,82 +2,66 @@
 #![feature(cell_extras)]
 #![feature(augmented_assignments)]
 #![feature(plugin)]
-//#![plugin(interpolate_idents)]
 #![plugin(clippy)]
 #![allow(needless_range_loop, match_bool)]
 
-//! Ethcore's ethereum implementation
+//! Ethcore library
 //!
-//! ### Rust version
+//! ### Rust version:
-//! - beta
 //! - nightly
 //!
 //! ### Supported platforms:
 //! - OSX
-//! - Linux/Ubuntu
+//! - Linux
 //!
-//! ### Dependencies:
+//! ### Building:
-//! - RocksDB 3.13
-//! - LLVM 3.7 (optional, required for `jit`)
-//! - evmjit (optional, required for `jit`)
 //!
-//! ### Dependencies Installation
+//! - Ubuntu 14.04 and later:
 //!
-//! - OSX
-//!
-//!   - rocksdb
 //!   ```bash
-//!   brew install rocksdb
+//!   # install rocksdb
+//!   add-apt-repository "deb http://ppa.launchpad.net/giskou/librocksdb/ubuntu trusty main"
+//!   apt-get update
+//!   apt-get install -y --force-yes librocksdb
+//!
+//!   # install multirust
+//!   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
+//!
+//!   # download and build parity
+//!   git clone https://github.com/ethcore/parity
+//!   cd parity
+//!   cargo build --release
 //!   ```
+//!   
+//! - OSX:
 //!
-//!   - llvm
+//!   ```bash
+//!   # install rocksdb && multirust
+//!   brew update
+//!   brew install rocksdb
+//!   brew install multirust
 //!
-//!       - download llvm 3.7 from http://llvm.org/apt/
+//!   # install nightly and make it default
+//!   multirust update nightly && multirust default nightly
 //!
-//!       ```bash
+//!   # export rust LIBRARY_PATH
-//!       cd llvm-3.7.0.src
+//!   export LIBRARY_PATH=/usr/local/lib
-//!       mkdir build && cd $_
-//!       cmake -G "Unix Makefiles" .. -DCMAKE_C_FLAGS_RELEASE= -DCMAKE_CXX_FLAGS_RELEASE= -DCMAKE_INSTALL_PREFIX=/usr/local/Cellar/llvm/3.7 -DCMAKE_BUILD_TYPE=Release
-//!       make && make install
-//!       ```
-//!   - evmjit
 //!
-//!       - download from https://github.com/debris/evmjit
+//!   # download and build parity
-//!
+//!   git clone https://github.com/ethcore/parity
-//!       ```bash
+//!   cd parity
-//!       cd evmjit
+//!   cargo build --release
-//!       mkdir build && cd $_
+//!   ```
-//!       cmake -DLLVM_DIR=/usr/local/lib/llvm-3.7/share/llvm/cmake ..
+
-//!       make && make install
+#[macro_use] extern crate log;
-//!       ```
+#[macro_use] extern crate ethcore_util as util;
-//!
+#[macro_use] extern crate lazy_static;
-//! - Linux/Ubuntu
-//!
-//!   - rocksdb
-//!
-//!     ```bash
-//!     wget https://github.com/facebook/rocksdb/archive/rocksdb-3.13.tar.gz
-//!     tar xvf rocksdb-3.13.tar.gz && cd rocksdb-rocksdb-3.13 && make shared_lib
-//!     sudo make install
-//!     ```
-//!
-//!   - llvm
-//!
-//!       - install using packages from http://llvm.org/apt/
-//!
-//!   - evmjit
-//!
-//!       - download from https://github.com/debris/evmjit
-//!
-//!       ```bash
-//!       cd evmjit
-//!       mkdir build && cd $_
-//!       cmake .. && make
-//!       sudo make install
-//!       sudo ldconfig
-//!       ```
-#[macro_use]
-extern crate log;
 extern crate rustc_serialize;
 extern crate flate2;
 extern crate rocksdb;
@@ -86,73 +70,42 @@ extern crate crypto;
 extern crate time;
 extern crate env_logger;
 extern crate num_cpus;
-#[cfg(feature = "jit" )]
-extern crate evmjit;
-#[macro_use]
-extern crate ethcore_util as util;
 extern crate crossbeam;
-#[macro_use]
-extern crate lazy_static;
 
-// NOTE: Add doc parser exception for these pub declarations.
+#[cfg(feature = "jit" )] extern crate evmjit;
 
-/// TODO [Gav Wood] Please document me
+pub mod block;
-pub mod common;
+pub mod blockchain;
-/// TODO [Tomusdrw] Please document me
+pub mod block_queue;
-pub mod basic_types;
+pub mod client;
-#[macro_use]
-pub mod evm;
 pub mod error;
-/// TODO [Gav Wood] Please document me
+pub mod ethereum;
-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 service;
-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;
 
-#[cfg(test)]
+mod common;
-mod tests;
+mod basic_types;
+#[macro_use] mod evm;
+mod log_entry;
+mod env_info;
+mod pod_account;
+mod pod_state;
+mod account_diff;
+mod state_diff;
+mod engine;
+mod state;
+mod account;
+mod action_params;
+mod transaction;
+mod receipt;
+mod null_engine;
+mod builtin;
+mod extras;
+mod substate;
+mod executive;
+mod externalities;
+mod verification;
 
-/// TODO [arkpar] Please document me
+#[cfg(test)] mod tests;
-pub mod client;
-/// TODO [arkpar] Please document me
-pub mod block;
-/// TODO [arkpar] Please document me
-pub mod verification;
-pub mod block_queue;
-pub mod ethereum;

ethcore/src/log_entry.rs

@@ -31,21 +31,6 @@ impl LogEntry {
 		}
 	}
 
-	/// Returns reference to address.
-	pub fn address(&self) -> &Address {
-		&self.address
-	}
-
-	/// Returns reference to topics.
-	pub fn topics(&self) -> &Vec<H256> {
-		&self.topics
-	}
-
-	/// Returns reference to data.
-	pub fn data(&self) -> &Bytes {
-		&self.data
-	}
-
 	/// Calculates the bloom of this log entry.
 	pub fn bloom(&self) -> LogBloom {
 		self.topics.iter().fold(LogBloom::from_bloomed(&self.address.sha3()), |b, t| b.with_bloomed(&t.sha3()))

ethcore/src/service.rs

@@ -1,3 +1,5 @@
+//! Creates and registers client and network services.
+
 use util::*;
 use spec::Spec;
 use error::*;
@@ -109,4 +111,4 @@ mod tests {
 		let service = ClientService::start(spec, NetworkConfiguration::new());
 		assert!(service.is_ok());
 	}
-}
+}

ethcore/src/spec.rs

@@ -1,3 +1,5 @@
+//! Parameters for a block chain.
+
 use common::*;
 use flate2::read::GzDecoder;
 use engine::*;
@@ -5,7 +7,7 @@ use pod_state::*;
 use null_engine::*;
 
 /// Converts file from base64 gzipped bytes to json
-pub fn gzip64res_to_json(source: &[u8]) -> Json {
+fn gzip64res_to_json(source: &[u8]) -> Json {
 	// there is probably no need to store genesis in based64 gzip,
 	// but that's what go does, and it was easy to load it this way
 	let data = source.from_base64().expect("Genesis block is malformed!");

ethcore/src/substate.rs

@@ -1,3 +1,4 @@
+//! Execution environment substate.
 use common::*;
 
 /// State changes which should be applied in finalize,
@@ -57,4 +58,4 @@ mod tests {
 		assert_eq!(sub_state.sstore_clears_count, x!(12));
 		assert_eq!(sub_state.suicides.len(), 1);
 	}
-}
+}

ethcore/src/transaction.rs

@@ -1,3 +1,5 @@
+//! Transaction data structure.
+
 use util::*;
 use basic_types::*;
 use error::*;
@@ -20,17 +22,17 @@ impl Default for Action {
 /// or contract creation operation.
 #[derive(Default, Debug, Clone)]
 pub struct Transaction {
-	/// TODO [debris] Please document me
+	/// Nonce.
 	pub nonce: U256,
-	/// TODO [debris] Please document me
+	/// Gas price.
 	pub gas_price: U256,
-	/// TODO [debris] Please document me
+	/// Gas paid up front for transaction execution.
 	pub gas: U256,
-	/// TODO [debris] Please document me
+	/// Action, can be either call or contract create.
 	pub action: Action,
-	/// TODO [debris] Please document me
+	/// Transfered value.
 	pub value: U256,
-	/// TODO [Gav Wood] Please document me
+	/// Transaction data.
 	pub data: Bytes,
 
 	// signature
@@ -96,19 +98,6 @@ impl Transaction {
 		}
 	}
 
-	/// Get the nonce of the transaction.
-	pub fn nonce(&self) -> &U256 { &self.nonce }
-	/// Get the gas price of the transaction.
-	pub fn gas_price(&self) -> &U256 { &self.gas_price }
-	/// Get the gas of the transaction.
-	pub fn gas(&self) -> &U256 { &self.gas }
-	/// Get the action of the transaction (Create or Call).
-	pub fn action(&self) -> &Action { &self.action }
-	/// Get the value of the transaction.
-	pub fn value(&self) -> &U256 { &self.value }
-	/// Get the data of the transaction.
-	pub fn data(&self) -> &Bytes { &self.data }
-
 	/// Append object into RLP stream, optionally with or without the signature.
 	pub fn rlp_append_opt(&self, s: &mut RlpStream, with_seal: Seal) {
 		s.begin_list(6 + match with_seal { Seal::With => 3, _ => 0 });