From ea13fd3c0ec92c44d56ecc422bf5edea78a10f84 Mon Sep 17 00:00:00 2001 From: debris Date: Mon, 1 Feb 2016 14:48:38 +0100 Subject: [PATCH 1/5] util docs cleanup pt.1 --- util/src/heapsizeof.rs | 2 ++ util/src/lib.rs | 49 +++++++++++++++++++++++++++++++----------- util/src/vector.rs | 38 +------------------------------- 3 files changed, 39 insertions(+), 50 deletions(-) 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/lib.rs b/util/src/lib.rs index 622fc950b..64cbac662 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; @@ -89,8 +114,7 @@ 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; @@ -114,7 +138,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/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 /// From 6ec672a1a64b8a20dcddf88d15d68357491bdd2f Mon Sep 17 00:00:00 2001 From: debris Date: Mon, 1 Feb 2016 14:58:13 +0100 Subject: [PATCH 2/5] docs for util standard, from_json and common modules --- util/src/common.rs | 2 ++ util/src/from_json.rs | 2 ++ util/src/lib.rs | 3 --- util/src/standard.rs | 2 ++ 4 files changed, 6 insertions(+), 3 deletions(-) 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/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/lib.rs b/util/src/lib.rs index 64cbac662..f422db7c8 100644 --- a/util/src/lib.rs +++ b/util/src/lib.rs @@ -82,13 +82,10 @@ 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; 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; From 2bddc938af6b3b95ed0a6cf2071fd1ccf948b2e9 Mon Sep 17 00:00:00 2001 From: debris Date: Mon, 1 Feb 2016 15:22:42 +0100 Subject: [PATCH 3/5] util docs --- util/src/crypto.rs | 2 + util/src/io/mod.rs | 76 +++++++++++++-------------- util/src/lib.rs | 12 +---- util/src/math.rs | 4 +- util/src/misc.rs | 2 + util/src/network/mod.rs | 99 ++++++++++++++++++------------------ util/src/semantic_version.rs | 2 + util/src/trie/mod.rs | 2 + 8 files changed, 101 insertions(+), 98 deletions(-) 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/io/mod.rs b/util/src/io/mod.rs index 1906e7438..3d8dd0109 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 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 +//! } +//! ``` mod service; mod worker; diff --git a/util/src/lib.rs b/util/src/lib.rs index f422db7c8..81828dd47 100644 --- a/util/src/lib.rs +++ b/util/src/lib.rs @@ -92,32 +92,24 @@ 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; 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; 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/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; From 205a1990d6ee7242ba87f3fe232bd9601515d021 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Mon, 1 Feb 2016 16:19:59 +0100 Subject: [PATCH 4/5] Update mod.rs --- util/src/io/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/util/src/io/mod.rs b/util/src/io/mod.rs index 3d8dd0109..4b53a46ae 100644 --- a/util/src/io/mod.rs +++ b/util/src/io/mod.rs @@ -1,6 +1,6 @@ //! General IO module. //! -//! Example usage for craeting a network service and adding an IO handler: +//! Example usage for creating a network service and adding an IO handler: //! //! ```rust //! extern crate ethcore_util; From 9ec2efb2f3f3d1b712afed0040f3811165fa4ba0 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Mon, 1 Feb 2016 16:20:46 +0100 Subject: [PATCH 5/5] Update mod.rs --- util/src/io/mod.rs | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/util/src/io/mod.rs b/util/src/io/mod.rs index 4b53a46ae..f81732ce1 100644 --- a/util/src/io/mod.rs +++ b/util/src/io/mod.rs @@ -13,20 +13,20 @@ //! 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); -//! } +//! 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();