Merge pull request #301 from ethcore/ethcore_docs

ethcore docs
This commit is contained in:
Gav Wood 2016-02-02 18:11:38 +01:00
commit 9ff75df73c
17 changed files with 126 additions and 181 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -2,82 +2,66 @@
#![feature(cell_extras)] #![feature(cell_extras)]
#![feature(augmented_assignments)] #![feature(augmented_assignments)]
#![feature(plugin)] #![feature(plugin)]
//#![plugin(interpolate_idents)]
#![plugin(clippy)] #![plugin(clippy)]
#![allow(needless_range_loop, match_bool)] #![allow(needless_range_loop, match_bool)]
//! Ethcore's ethereum implementation //! Ethcore library
//! //!
//! ### Rust version //! ### Rust version:
//! - beta
//! - nightly //! - nightly
//! //!
//! ### Supported platforms: //! ### Supported platforms:
//! - OSX //! - 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 //! ```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 rustc_serialize;
extern crate flate2; extern crate flate2;
extern crate rocksdb; extern crate rocksdb;
@ -86,73 +70,42 @@ extern crate crypto;
extern crate time; extern crate time;
extern crate env_logger; extern crate env_logger;
extern crate num_cpus; extern crate num_cpus;
#[cfg(feature = "jit" )]
extern crate evmjit;
#[macro_use]
extern crate ethcore_util as util;
extern crate crossbeam; 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; 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; 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 spec;
pub mod views; 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;

View File

@ -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. /// Calculates the bloom of this log entry.
pub fn bloom(&self) -> LogBloom { pub fn bloom(&self) -> LogBloom {
self.topics.iter().fold(LogBloom::from_bloomed(&self.address.sha3()), |b, t| b.with_bloomed(&t.sha3())) self.topics.iter().fold(LogBloom::from_bloomed(&self.address.sha3()), |b, t| b.with_bloomed(&t.sha3()))

View File

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

View File

@ -1,3 +1,5 @@
//! Parameters for a block chain.
use common::*; use common::*;
use flate2::read::GzDecoder; use flate2::read::GzDecoder;
use engine::*; use engine::*;
@ -5,7 +7,7 @@ use pod_state::*;
use null_engine::*; use null_engine::*;
/// Converts file from base64 gzipped bytes to json /// 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, // 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 // 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!"); let data = source.from_base64().expect("Genesis block is malformed!");

View File

@ -1,3 +1,4 @@
//! Execution environment substate.
use common::*; use common::*;
/// State changes which should be applied in finalize, /// 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.sstore_clears_count, x!(12));
assert_eq!(sub_state.suicides.len(), 1); assert_eq!(sub_state.suicides.len(), 1);
} }
} }

View File

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