add docs to everything that was undocumented

src/lib.rs

@@ -1,3 +1,5 @@
+#![deny(missing_docs)]
+
 //! `bincode` is a crate for encoding and decoding using a tiny binary
 //! serialization strategy.
 //!
@@ -7,11 +9,11 @@
 //! 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`.
+//! Until "default type parameters" lands, we have an extra module called `endian_choice`
+//! that duplicates all of the core bincode functionality but with the option to choose
+//! which endianness the integers are encoded using.
+//!
+//! The default endianness is little.
 //!
 //! ### Using Basic Functions
 //!
@@ -34,14 +36,13 @@
 #![crate_type = "rlib"]
 #![crate_type = "dylib"]
 
-#![doc(html_logo_url = "./icon.png")]
-
 extern crate byteorder;
 extern crate num_traits;
 extern crate serde as serde_crate;
 
 mod serde;
 
+/// All of the core bincode functions and types with the ability to choose endianness.
 pub mod endian_choice {
     pub use super::serde::{Deserializer, Serializer, serialize, serialize_into, deserialize, deserialize_from};
 }
@@ -50,7 +51,9 @@ use std::io::{Read, Write};
 
 pub use serde::{ErrorKind, Error, Result, serialized_size, serialized_size_bounded};
 
+/// A Deserializer that uses LittleEndian byteorder
 pub type Deserializer<W, S> = serde::Deserializer<W, S, byteorder::LittleEndian>;
+/// A Serializer that uses LittleEndian byteorder
 pub type Serializer<W> = serde::Serializer<W, byteorder::LittleEndian>;
 
 /// Deserializes a slice of bytes into an object.
@@ -121,13 +124,20 @@ pub fn serialize<T: ?Sized, S>(value: &T, size_limit: S) -> serde::Result<Vec<u8
 /// within that limit.  This verification occurs before any bytes are written to
 /// the Writer, so recovering from an error is easy.
 pub trait SizeLimit {
+    /// Tells the SizeLimit that a certain number of bytes has been
+    /// read or written.  Returns Err if the limit has been exceeded.
     fn add(&mut self, n: u64) -> Result<()>;
+    /// Returns the hard limit (if one exists)
     fn limit(&self) -> Option<u64>;
 }
 
+/// A SizeLimit that restricts serialized or deserialized messages from
+/// exceeding a certain byte length.
 #[derive(Copy, Clone)]
 pub struct Bounded(pub u64);
 
+/// A SizeLimit without a limit!
+/// Use this if you don't care about the size of encoded or decoded messages.
 #[derive(Copy, Clone)]
 pub struct Infinite;
 

src/serde/mod.rs

@@ -23,6 +23,7 @@ use serde_crate as serde;
 mod reader;
 mod writer;
 
+/// The result of a serialization or deserialization operation.
 pub type Result<T> = result::Result<T, Error>;
 
 /// An error that can be produced during (de)serializing.
@@ -31,6 +32,7 @@ pub type Result<T> = result::Result<T, Error>;
 /// in an invalid state.
 pub type Error = Box<ErrorKind>;
 
+/// The kind of error that can be produced during a serialization or deserialization.
 #[derive(Debug)]
 pub enum ErrorKind {
     /// If the error stems from the reader/writer that is being used
@@ -40,14 +42,18 @@ pub enum ErrorKind {
     /// encoding, this error will be returned.  This error is only possible
     /// if a stream is corrupted.  A stream produced from `encode` or `encode_into`
     /// should **never** produce an InvalidEncoding error.
-    InvalidEncoding{
+    InvalidEncoding {
+        #[allow(missing_docs)]
         desc: &'static str,
+        #[allow(missing_docs)]
         detail: Option<String>
     },
     /// If (de)serializing a message takes more than the provided size limit, this
     /// error is returned.
     SizeLimit,
+    /// Bincode can not encode sequences of unknown length (like iterators).
     SequenceMustHaveLength,
+    /// A custom error message from Serde.
     Custom(String)
 }
 

src/serde/reader.rs

@@ -16,6 +16,9 @@ const BLOCK_SIZE: usize = 65536;
 /// This struct should rarely be used.
 /// In most cases, prefer the `decode_from` function.
 ///
+/// The ByteOrder that is chosen will impact the endianness that
+/// is used to read integers out of the reader.
+///
 /// ```rust,ignore
 /// let d = Deserializer::new(&mut some_reader, SizeLimit::new());
 /// serde::Deserialize::deserialize(&mut deserializer);
@@ -29,6 +32,7 @@ pub struct Deserializer<R, S: SizeLimit, E: ByteOrder> {
 }
 
 impl<R: Read, E: ByteOrder, S: SizeLimit> Deserializer<R, S, E> {
+    /// Creates a new Deserializer with a given `Read`er and a size_limit.
     pub fn new(r: R, size_limit: S) -> Deserializer<R, S, E> {
         Deserializer {
             reader: r,

src/serde/writer.rs

@@ -11,6 +11,9 @@ use super::super::SizeLimit;
 
 /// An Serializer that encodes values directly into a Writer.
 ///
+/// The specified byte-order will impact the endianness that is
+/// used during the encoding.
+///
 /// This struct should not be used often.
 /// For most cases, prefer the `encode_into` function.
 pub struct Serializer<W, E: ByteOrder> {
@@ -19,6 +22,7 @@ pub struct Serializer<W, E: ByteOrder> {
 }
 
 impl<W: Write, E: ByteOrder> Serializer<W, E> {
+    /// Creates a new Serializer with the given `Write`r.
     pub fn new(w: W) -> Serializer<W, E> {
         Serializer {
             writer: w,