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`
+//! Until "default type parameters" lands, we have an extra module called `endian_choice`
-//! or the `serde` crate.  `rustc_serialize` and `serde` are crates and and also the names of their
+//! that duplicates all of the core bincode functionality but with the option to choose
-//! corresponding modules inside of `bincode`.  Both modules have exactly equivalant functions, and
+//! which endianness the integers are encoded using.
-//! and the only difference is whether or not the library user wants to use `rustc_serialize` or
+//!
-//! `serde`.
+//! 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 {
-        desc: &'static str, 
+        #[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)
 }
 
@@ -194,7 +200,7 @@ pub fn serialized_size<T: ?Sized>(value: &T) -> u64
 ///
 /// If it can be serialized in `max` or fewer bytes, that number will be returned
 /// inside `Some`.  If it goes over bounds, then None is returned.
-pub fn serialized_size_bounded<T: ?Sized>(value: &T, max: u64) -> Option<u64> 
+pub fn serialized_size_bounded<T: ?Sized>(value: &T, max: u64) -> Option<u64>
     where T: serde::Serialize
 {
     let mut size_counter = SizeChecker {

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,
@@ -227,7 +231,7 @@ where R: Read, S: SizeLimit, E: ByteOrder {
 
         visitor.visit_enum(self)
     }
-    
+
     fn deserialize_tuple<V>(self, _len: usize, visitor: V) -> Result<V::Value>
         where V: serde::de::Visitor,
     {
@@ -330,7 +334,7 @@ where R: Read, S: SizeLimit, E: ByteOrder {
                 let value = try!(serde::de::DeserializeSeed::deserialize(seed, &mut *self.deserializer));
                 Ok(value)
             }
-            
+
             fn size_hint(&self) -> (usize, Option<usize>) {
                 (self.len, Some(self.len))
             }

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,
@@ -392,8 +396,8 @@ impl<'a, W, E> serde::ser::SerializeSeq for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -411,8 +415,8 @@ impl<'a, W, E> serde::ser::SerializeTuple for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -430,8 +434,8 @@ impl<'a, W, E> serde::ser::SerializeTupleStruct for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -449,8 +453,8 @@ impl<'a, W, E> serde::ser::SerializeTupleVariant for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -468,15 +472,15 @@ impl<'a, W, E> serde::ser::SerializeMap for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()> 
+    fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()>
-    where K: serde::ser::Serialize 
+    where K: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
 
         #[inline]
-    fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()> 
+    fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()>
-    where V: serde::ser::Serialize 
+    where V: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -494,8 +498,8 @@ impl<'a, W, E> serde::ser::SerializeStruct for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -513,8 +517,8 @@ impl<'a, W, E> serde::ser::SerializeStructVariant for Compound<'a, W, E>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -536,8 +540,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeSeq for SizeCompound<'a, S>
     type Error = Error;
 
     #[inline]
-    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -554,8 +558,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTuple for SizeCompound<'a, S>
     type Error = Error;
 
     #[inline]
-    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -572,8 +576,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTupleStruct for SizeCompound<'a, S>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -590,8 +594,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTupleVariant for SizeCompound<'a, S>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -608,15 +612,15 @@ impl<'a, S: SizeLimit + 'a> serde::ser::SerializeMap for SizeCompound<'a, S>
     type Error = Error;
 
     #[inline]
-    fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()> 
+    fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()>
-    where K: serde::ser::Serialize 
+    where K: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
 
         #[inline]
-    fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()> 
+    fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()>
-    where V: serde::ser::Serialize 
+    where V: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -633,8 +637,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeStruct for SizeCompound<'a, S>
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }
@@ -651,8 +655,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeStructVariant for SizeCompound<'a, S
     type Error = Error;
 
     #[inline]
-    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()> 
+    fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
-    where T: serde::ser::Serialize 
+    where T: serde::ser::Serialize
     {
         value.serialize(&mut *self.ser)
     }