diff --git a/util/src/common.rs b/util/src/common.rs index 0f10a4e97..9cf7a3765 100644 --- a/util/src/common.rs +++ b/util/src/common.rs @@ -1,3 +1,5 @@ +//! Utils common types and macros global reexport. + pub use standard::*; pub use from_json::*; pub use error::*; diff --git a/util/src/crypto.rs b/util/src/crypto.rs index 79a952a94..8a56c8827 100644 --- a/util/src/crypto.rs +++ b/util/src/crypto.rs @@ -1,3 +1,5 @@ +//! Ethcore crypto. + use hash::*; use bytes::*; use uint::*; diff --git a/util/src/from_json.rs b/util/src/from_json.rs index 1d95df691..7319ec8aa 100644 --- a/util/src/from_json.rs +++ b/util/src/from_json.rs @@ -1,3 +1,5 @@ +//! Coversion from json. + use standard::*; #[macro_export] diff --git a/util/src/heapsizeof.rs b/util/src/heapsizeof.rs index c6d4cace4..8dcc53728 100644 --- a/util/src/heapsizeof.rs +++ b/util/src/heapsizeof.rs @@ -1,3 +1,5 @@ +//! Calculates heapsize of util types. + use uint::*; use hash::*; diff --git a/util/src/io/mod.rs b/util/src/io/mod.rs index 1906e7438..f81732ce1 100644 --- a/util/src/io/mod.rs +++ b/util/src/io/mod.rs @@ -1,41 +1,41 @@ -/// General IO module. -/// -/// Example usage for craeting a network service and adding an IO handler: -/// -/// ```rust -/// extern crate ethcore_util; -/// use ethcore_util::*; -/// -/// struct MyHandler; -/// -/// #[derive(Clone)] -/// struct MyMessage { -/// data: u32 -/// } -/// -/// impl IoHandler for MyHandler { -/// fn initialize(&self, io: &IoContext) { -/// io.register_timer(0, 1000).unwrap(); -/// } -/// -/// fn timeout(&self, _io: &IoContext, timer: TimerToken) { -/// println!("Timeout {}", timer); -/// } -/// -/// fn message(&self, _io: &IoContext, message: &MyMessage) { -/// println!("Message {}", message.data); -/// } -/// } -/// -/// fn main () { -/// let mut service = IoService::::start().expect("Error creating network service"); -/// service.register_handler(Arc::new(MyHandler)).unwrap(); -/// -/// // Wait for quit condition -/// // ... -/// // Drop the service -/// } -/// ``` +//! General IO module. +//! +//! Example usage for creating a network service and adding an IO handler: +//! +//! ```rust +//! extern crate ethcore_util; +//! use ethcore_util::*; +//! +//! struct MyHandler; +//! +//! #[derive(Clone)] +//! struct MyMessage { +//! data: u32 +//! } +//! +//! impl IoHandler for MyHandler { +//! fn initialize(&self, io: &IoContext) { +//! io.register_timer(0, 1000).unwrap(); +//! } +//! +//! fn timeout(&self, _io: &IoContext, timer: TimerToken) { +//! println!("Timeout {}", timer); +//! } +//! +//! fn message(&self, _io: &IoContext, message: &MyMessage) { +//! println!("Message {}", message.data); +//! } +//! } +//! +//! fn main () { +//! let mut service = IoService::::start().expect("Error creating network service"); +//! service.register_handler(Arc::new(MyHandler)).unwrap(); +//! +//! // Wait for quit condition +//! // ... +//! // Drop the service +//! } +//! ``` mod service; mod worker; diff --git a/util/src/lib.rs b/util/src/lib.rs index 622fc950b..81828dd47 100644 --- a/util/src/lib.rs +++ b/util/src/lib.rs @@ -8,30 +8,55 @@ //! Ethcore-util library //! //! ### Rust version: -//! - beta //! - nightly //! //! ### Supported platforms: //! - OSX //! - Linux //! -//! ### Dependencies: -//! - RocksDB 3.13 +//! ### Building: //! -//! ### Dependencies Installation: +//! - Ubuntu 14.04 and later: //! +//! ```bash +//! # 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: //! //! ```bash +//! # install rocksdb && multirust +//! brew update //! brew install rocksdb -//! ``` +//! brew install multirust //! -//! - From source: +//! # install nightly and make it default +//! multirust update nightly && multirust default nightly //! -//! ```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 +//! # 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 //! ``` extern crate slab; @@ -57,46 +82,34 @@ extern crate serde; #[macro_use] extern crate log as rlog; -/// 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; +mod json_aid; pub mod vector; pub mod sha3; pub mod hashdb; pub mod memorydb; pub mod overlaydb; pub mod journaldb; -/// TODO [Gav Wood] Please document me -pub mod math; +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; +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 mod log; @@ -114,7 +127,6 @@ pub use crypto::*; pub use triehash::*; pub use trie::*; pub use nibbleslice::*; -pub use heapsizeof::*; pub use squeeze::*; pub use semantic_version::*; pub use network::*; diff --git a/util/src/math.rs b/util/src/math.rs index c85c4653e..71533ec26 100644 --- a/util/src/math.rs +++ b/util/src/math.rs @@ -1,4 +1,6 @@ -/// log2 +//! Common math functions. + +/// Returns log2. pub fn log2(x: usize) -> u32 { if x <= 1 { return 0; diff --git a/util/src/misc.rs b/util/src/misc.rs index 316e78a11..f0e34d4c9 100644 --- a/util/src/misc.rs +++ b/util/src/misc.rs @@ -1,3 +1,5 @@ +//! Diff misc. + use common::*; #[derive(Debug,Clone,PartialEq,Eq)] diff --git a/util/src/network/mod.rs b/util/src/network/mod.rs index 668cdc8b1..52f6ba382 100644 --- a/util/src/network/mod.rs +++ b/util/src/network/mod.rs @@ -1,52 +1,53 @@ -/// Network and general IO module. -/// Example usage for craeting a network service and adding an IO handler: -/// -/// ```rust -/// extern crate ethcore_util as util; -/// use util::*; -/// -/// struct MyHandler; -/// -/// #[derive(Clone)] -/// struct MyMessage { -/// data: u32 -/// } -/// -/// impl NetworkProtocolHandler for MyHandler { -/// fn initialize(&self, io: &NetworkContext) { -/// io.register_timer(0, 1000); -/// } -/// -/// fn read(&self, io: &NetworkContext, peer: &PeerId, packet_id: u8, data: &[u8]) { -/// println!("Received {} ({} bytes) from {}", packet_id, data.len(), peer); -/// } -/// -/// fn connected(&self, io: &NetworkContext, peer: &PeerId) { -/// println!("Connected {}", peer); -/// } -/// -/// fn disconnected(&self, io: &NetworkContext, peer: &PeerId) { -/// println!("Disconnected {}", peer); -/// } -/// -/// fn timeout(&self, io: &NetworkContext, timer: TimerToken) { -/// println!("Timeout {}", timer); -/// } -/// -/// fn message(&self, io: &NetworkContext, message: &MyMessage) { -/// println!("Message {}", message.data); -/// } -/// } -/// -/// fn main () { -/// let mut service = NetworkService::::start(NetworkConfiguration::new()).expect("Error creating network service"); -/// service.register_protocol(Arc::new(MyHandler), "myproto", &[1u8]); -/// -/// // Wait for quit condition -/// // ... -/// // Drop the service -/// } -/// ``` +//! Network and general IO module. +//! +//! Example usage for craeting a network service and adding an IO handler: +//! +//! ```rust +//! extern crate ethcore_util as util; +//! use util::*; +//! +//! struct MyHandler; +//! +//! #[derive(Clone)] +//! struct MyMessage { +//! data: u32 +//! } +//! +//! impl NetworkProtocolHandler for MyHandler { +//! fn initialize(&self, io: &NetworkContext) { +//! io.register_timer(0, 1000); +//! } +//! +//! fn read(&self, io: &NetworkContext, peer: &PeerId, packet_id: u8, data: &[u8]) { +//! println!("Received {} ({} bytes) from {}", packet_id, data.len(), peer); +//! } +//! +//! fn connected(&self, io: &NetworkContext, peer: &PeerId) { +//! println!("Connected {}", peer); +//! } +//! +//! fn disconnected(&self, io: &NetworkContext, peer: &PeerId) { +//! println!("Disconnected {}", peer); +//! } +//! +//! fn timeout(&self, io: &NetworkContext, timer: TimerToken) { +//! println!("Timeout {}", timer); +//! } +//! +//! fn message(&self, io: &NetworkContext, message: &MyMessage) { +//! println!("Message {}", message.data); +//! } +//! } +//! +//! fn main () { +//! let mut service = NetworkService::::start(NetworkConfiguration::new()).expect("Error creating network service"); +//! service.register_protocol(Arc::new(MyHandler), "myproto", &[1u8]); +//! +//! // Wait for quit condition +//! // ... +//! // Drop the service +//! } +//! ``` mod host; mod connection; mod handshake; diff --git a/util/src/semantic_version.rs b/util/src/semantic_version.rs index 92f6ea376..10cf47eac 100644 --- a/util/src/semantic_version.rs +++ b/util/src/semantic_version.rs @@ -1,3 +1,5 @@ +//! Semantic version formatting and comparing. + /// A version value with strict meaning. Use `to_u32` to convert to a simple integer. /// /// # Example diff --git a/util/src/standard.rs b/util/src/standard.rs index 873df6cb4..d1589d30a 100644 --- a/util/src/standard.rs +++ b/util/src/standard.rs @@ -1,3 +1,5 @@ +//! Std lib global reexports. + pub use std::io; pub use std::fs; pub use std::str; diff --git a/util/src/trie/mod.rs b/util/src/trie/mod.rs index ce796bd15..502a7688d 100644 --- a/util/src/trie/mod.rs +++ b/util/src/trie/mod.rs @@ -1,3 +1,5 @@ +//! Trie interface and implementation. + /// TODO [Gav Wood] Please document me pub mod trietraits; pub mod standardmap; diff --git a/util/src/vector.rs b/util/src/vector.rs index 94b5ee70c..b9770e30b 100644 --- a/util/src/vector.rs +++ b/util/src/vector.rs @@ -1,40 +1,4 @@ -//! vector util functions - -use std::ptr; - -/// TODO [debris] Please document me -pub trait InsertSlice { - /// TODO [debris] Please document me - fn insert_slice(&mut self, index: usize, elements: &[T]); -} - -/// based on `insert` function implementation from standard library -impl InsertSlice for Vec { - fn insert_slice(&mut self, index: usize, elements: &[T]) { - let e_len = elements.len(); - if e_len == 0 { - return; - } - - let len = self.len(); - assert!(index <= len); - - // space for the new element - self.reserve(e_len); - - unsafe { - { - let p = self.as_mut_ptr().offset(index as isize); - let ep = elements.as_ptr().offset(0); - // shift everything by e_len, to make space - ptr::copy(p, p.offset(e_len as isize), len - index); - // write new element - ptr::copy(ep, p, e_len); - } - self.set_len(len + e_len); - } - } -} +//! Vector extensions. /// Returns len of prefix shared with elem ///