From 111fc70d0b165324d380dc73570af93d91beb3fb Mon Sep 17 00:00:00 2001
From: debris <marek.kotewicz@gmail.com>
Date: Sat, 28 Nov 2015 03:58:37 +0100
Subject: [PATCH] updated docs

---
 src/bytes.rs | 46 ++++++++++++++++++++++++++++++++++++++++------
 src/hash.rs  |  2 +-
 src/lib.rs   |  5 +++++
 3 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/src/bytes.rs b/src/bytes.rs
index 9521abdbd..0f82748a1 100644
--- a/src/bytes.rs
+++ b/src/bytes.rs
@@ -1,17 +1,47 @@
-//! To/From Bytes conversation for basic types
-//!
-//! Types implementing `ToBytes` and `FromBytes` traits
-//! can be easily converted to and from bytes
+//! Unified interfaces for bytes operations on basic types
 //! 
 //! # Examples
+//! ```rust
+//! extern crate ethcore_util as util;
+//! 
+//! fn bytes_convertable() {
+//! 	use util::bytes::BytesConvertable;
 //!
+//! 	let arr = [0; 5];
+//! 	let slice: &[u8] = arr.bytes();
+//! }
+//! 
+//! fn to_bytes() {
+//! 	use util::bytes::ToBytes;
+//! 	
+//! 	let a: Vec<u8> = "hello_world".to_bytes();
+//! 	let b: Vec<u8> = 400u32.to_bytes();
+//! 	let c: Vec<u8> = 0xffffffffffffffffu64.to_bytes();
+//! }
+//! 
+//! fn from_bytes() {
+//! 	use util::bytes::FromBytes;
+//! 	
+//! 	let a = String::from_bytes(&[b'd', b'o', b'g']);
+//! 	let b = u8::from_bytes(&[0xfa]);
+//! 	let c = u64::from_bytes(&[0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff]);
+//! }
+//!
+//! fn main() {
+//! 	bytes_convertable();
+//! 	to_bytes();
+//! 	from_bytes();
+//! }
+//! ```
 
 use std::fmt;
 use std::error::Error as StdError;
 use uint::{U128, U256};
 
+/// Vector of bytes
 pub type Bytes = Vec<u8>;
 
+/// Slice of bytes to underlying memory
 pub trait BytesConvertable {
 	fn bytes(&self) -> &[u8];
 }
@@ -46,6 +76,8 @@ fn bytes_convertable() {
     assert_eq!([0u8; 0].bytes(), &[]);
 }
 
+/// Converts given type to its shortest representation in bytes
+///
 /// TODO: optimise some conversations
 pub trait ToBytes {
 	fn to_bytes(&self) -> Vec<u8>;
@@ -141,6 +173,7 @@ macro_rules! impl_uint_to_bytes {
 impl_uint_to_bytes!(U256);
 impl_uint_to_bytes!(U128);
 
+/// Error returned when FromBytes conversation goes wrong
 #[derive(Debug, PartialEq, Eq)]
 pub enum FromBytesError {
 	UnexpectedEnd
@@ -156,10 +189,11 @@ impl fmt::Display for FromBytesError {
 	}
 }
 
+/// Alias for the result of FromBytes trait
 pub type FromBytesResult<T> = Result<T, FromBytesError>;
 
-/// implements "Sized", so the compiler can deducate the size
-/// of the return type
+/// Converts to given type from its bytes representation
+///
 /// TODO: check size of bytes before conversation and return appropriate error
 pub trait FromBytes: Sized {
 	fn from_bytes(bytes: &[u8]) -> FromBytesResult<Self>;
diff --git a/src/hash.rs b/src/hash.rs
index 8612cf226..0dfd4f487 100644
--- a/src/hash.rs
+++ b/src/hash.rs
@@ -23,7 +23,7 @@ pub trait FixedHash: Sized + BytesConvertable {
 macro_rules! impl_hash {
 	($from: ident, $size: expr) => {
 		#[derive(Eq)]
-		pub struct $from (pub [u8; $size]);
+		pub struct $from ([u8; $size]);
 
 		impl BytesConvertable for $from {
 			fn bytes(&self) -> &[u8] {
diff --git a/src/lib.rs b/src/lib.rs
index f94bceb86..acb03afb5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,7 @@
+//! Ethcore-util library
+//! 
+//! TODO: check reexports
+
 extern crate rustc_serialize;
 extern crate mio;
 extern crate rand;
@@ -20,6 +24,7 @@ pub mod math;
 
 //pub mod network;
 
+// reexports
 pub use std::str::FromStr;
 pub use hash::*;
 pub use sha3::*;