Doc: minor documentation update.

Also fixed some markdown bugs, fixes #31.

Author: 3Hren

src/decode.rs

@@ -1,4 +1,4 @@
-//! # Note
+//! Provides various functions and structs for MessagePack decoding.
 //!
 //! Most of the function defined in this module will silently handle interruption error (EINTR)
 //! received from the given `Read` to be in consistent state with the `Write::write_all` method in
@@ -1153,6 +1153,8 @@ pub fn read_map_size<R>(rd: &mut R) -> Result<u32, ValueReadError>
     }
 }
 
+/// Attempts to read up to 5 bytes from the given reader and to decode them as Binary array length.
+///
 /// # Note
 ///
 /// This function will silently retry on every EINTR received from the underlying `Read` until
@@ -1169,10 +1171,19 @@ pub fn read_bin_len<R>(rd: &mut R) -> Result<u32, ValueReadError>
     }
 }
 
+/// Attempts to read some bytes from the given slice until a complete Binary message is decoded,
+/// returning a borrowed slice with the data.
+///
+/// This includes reading both length and the data itself.
+///
 /// # Note
 ///
 /// This function will silently retry on every EINTR received from the underlying `Read` until
 /// successful read.
+///
+/// # Unstable
+///
+/// This function is unstable, moreover I have a plan to drop it.
 // TODO: Docs; not sure about naming.
 pub fn read_bin_borrow(rd: &[u8]) -> Result<&[u8], ValueReadError> {
     let mut cur = io::Cursor::new(rd);

src/encode.rs

@@ -1,3 +1,5 @@
+//! Provides various functions and structs for MessagePack encoding.
+
 use std::convert::From;
 use std::error::Error;
 use std::fmt;
@@ -846,6 +848,8 @@ impl From<ValueWriteError> for Error {
     }
 }
 
+/// Encodes and attempts to write the most efficient representation of the given Value.
+///
 /// # Note
 ///
 /// All instances of `ErrorKind::Interrupted` are handled by this function and the underlying

src/value.rs

@@ -1,3 +1,5 @@
+//! Contains Value and ValueRef structs and its conversion traits.
+
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub enum Integer {
     /// Every non-negative integer is treated as u64, even if it fits in i64.