From 2bddc938af6b3b95ed0a6cf2071fd1ccf948b2e9 Mon Sep 17 00:00:00 2001 From: debris Date: Mon, 1 Feb 2016 15:22:42 +0100 Subject: [PATCH] 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;