add docs for the new modules

src/lib.rs

@@ -6,6 +6,13 @@
 //! functions which respectively allow encoding into a `std::io::Writer`
 //! and decoding from a `std::io::Buffer`.
 //!
+//! ## Modules
+//! There are two ways to encode and decode structs using `bincode`, either using `rustc_serialize`
+//! or the `serde` crate.  `rustc_serialize` and `serde` are crates and and also the names of their
+//! corresponding modules inside of `bincode`.  Both modules have exactly equivalant functions, and
+//! and the only difference is whether or not the library user wants to use `rustc_serialize` or
+//! `serde`.
+//!
 //! ### Using Basic Functions
 //!
 //! ```rust

src/rustc_serialize/mod.rs

@@ -1,3 +1,7 @@
+//! A collection of serialization and deserialization functions
+//! that use the `rustc_serialize` crate for the encodable and decodable
+//! implementation.
+
 use rustc_serialize_crate::{Encodable, Decodable};
 use std::io::{Write, Read};
 use ::SizeLimit;

src/serde/mod.rs

@@ -1,3 +1,7 @@
+//! A collection of serialization and deserialization functions
+//! that use the `serde` crate for the serialazble and deserializable
+//! implementation.
+
 use std::io::{Write, Read};
 use ::SizeLimit;
 
@@ -20,11 +24,16 @@ use serde_crate as serde;
 mod reader;
 mod writer;
 
-pub fn serialize_into<W, T>(writer: &mut W,
+/// Serializes an object directly into a `Writer`.
-                       value: &T,
+///
-                       size_limit: SizeLimit) -> SerializeResult<()>
+/// If the serialization would take more bytes than allowed by `size_limit`, an error
-    where W: Write,
+/// is returned and *no bytes* will be written into the `Writer`.
-          T: serde::Serialize,
+///
+/// If this returns an `SerializeError` (other than SizeLimit), assume that the
+/// writer is in an invalid state, as writing could bail out in the middle of
+/// serializing.
+pub fn serialize_into<W, T>(writer: &mut W, value: &T, size_limit: SizeLimit) -> SerializeResult<()>
+    where W: Write, T: serde::Serialize,
 {
     match size_limit {
         SizeLimit::Infinite => { }
@@ -38,6 +47,10 @@ pub fn serialize_into<W, T>(writer: &mut W,
     serde::Serialize::serialize(value, &mut serializer)
 }
 
+/// Serializes a serializable object into a `Vec` of bytes.
+///
+/// If the serialization would take more bytes than allowed by `size_limit`,
+/// an error is returned.
 pub fn serialize<T>(value: &T, size_limit: SizeLimit) -> SerializeResult<Vec<u8>>
     where T: serde::Serialize,
 {
@@ -80,6 +93,15 @@ pub fn serialized_size_bounded<T: serde::Serialize>(value: &T, max: u64) -> Opti
     value.serialize(&mut size_checker).ok().map(|_| size_checker.written)
 }
 
+/// Deserializes an object directly from a `Buffer`ed Reader.
+///
+/// If the provided `SizeLimit` is reached, the deserialization will bail immediately.
+/// A SizeLimit can help prevent an attacker from flooding your server with
+/// a neverending stream of values that runs your server out of memory.
+///
+/// If this returns an `DeserializeError`, assume that the buffer that you passed
+/// in is in an invalid state, as the error could be returned during any point
+/// in the reading.
 pub fn deserialize_from<R, T>(reader: &mut R, size_limit: SizeLimit) -> DeserializeResult<T>
     where R: Read,
           T: serde::Deserialize,
@@ -88,6 +110,10 @@ pub fn deserialize_from<R, T>(reader: &mut R, size_limit: SizeLimit) -> Deserial
     serde::Deserialize::deserialize(&mut deserializer)
 }
 
+/// Deserializes a slice of bytes into an object.
+///
+/// This method does not have a size-limit because if you already have the bytes
+/// in memory, then you don't gain anything by having a limiter.
 pub fn deserialize<T>(bytes: &[u8]) -> DeserializeResult<T>
     where T: serde::Deserialize,
 {