Added missing documentation, removed ToBson.

Author: SpaceManiac

src/bson.rs

@@ -29,6 +29,7 @@ use rustc_serialize::hex::ToHex;
 
 use spec::{ElementType, BinarySubtype};
 
+/// Possible BSON value types.
 #[derive(Debug, Clone)]
 pub enum Bson {
     FloatingPoint(f64),
@@ -49,10 +50,13 @@ pub enum Bson {
     UtcDatetime(DateTime<UTC>),
 }
 
+/// Alias for `Vec<Bson>`.
 pub type Array = Vec<Bson>;
+/// Alias for `BTreeMap<String, Bson>`.
 pub type Document = BTreeMap<String, Bson>;
 
 impl Bson {
+    /// Get the `ElementType` of this value.
     pub fn element_type(&self) -> ElementType {
         match self {
             &Bson::FloatingPoint(..) => ElementType::FloatingPoint,
@@ -74,6 +78,7 @@ impl Bson {
         }
     }
 
+    /// Convert this value to the best approximate `Json`.
     pub fn to_json(&self) -> json::Json {
         match self {
             &Bson::FloatingPoint(v) => json::Json::F64(v),
@@ -120,6 +125,7 @@ impl Bson {
         }
     }
 
+    /// Create a `Bson` from a `Json`.
     pub fn from_json(j: &json::Json) -> Bson {
         match j {
             &json::Json::I64(x) => Bson::I64(x),
@@ -133,25 +139,3 @@ impl Bson {
         }
     }
 }
-
-pub trait ToBson {
-    fn to_bson(&self) -> Bson;
-}
-
-impl ToBson for str {
-    fn to_bson(&self) -> Bson {
-        Bson::String(self.to_owned())
-    }
-}
-
-impl<T: ToBson> ToBson for [T] {
-    fn to_bson(&self) -> Bson {
-        Bson::Array(self.iter().map(|x| x.to_bson()).collect())
-    }
-}
-
-impl<T: ToBson> ToBson for BTreeMap<String, T> {
-    fn to_bson(&self) -> Bson {
-        Bson::Document(self.iter().map(|(k, v)| (k.clone(), v.to_bson())).collect())
-    }
-}

src/decoder.rs

@@ -30,6 +30,7 @@ use chrono::{DateTime, NaiveDateTime, UTC};
 use spec::{self, BinarySubtype};
 use bson::{Bson, Array, Document};
 
+/// Possible errors that can arise during decoding.
 #[derive(Debug)]
 pub enum DecoderError {
     IoError(io::Error),
@@ -89,6 +90,7 @@ impl error::Error for DecoderError {
     }
 }
 
+/// Alias for `Result<T, DecoderError>`.
 pub type DecoderResult<T> = Result<T, DecoderError>;
 
 fn read_string<R: Read + ?Sized>(reader: &mut R) -> DecoderResult<String> {
@@ -123,6 +125,7 @@ fn read_i64<R: Read + ?Sized>(reader: &mut R) -> DecoderResult<i64> {
     reader.read_i64::<LittleEndian>().map_err(From::from)
 }
 
+/// Attempt to decode a `Document` from a byte stream.
 pub fn decode_document<R: Read + ?Sized>(reader: &mut R) -> DecoderResult<Document> {
     let mut doc = Document::new();
 

src/encoder.rs

@@ -29,6 +29,7 @@ use byteorder::{self, LittleEndian, WriteBytesExt};
 
 use bson::Bson;
 
+/// Possible errors that can arise during encoding.
 #[derive(Debug)]
 pub enum EncoderError {
     IoError(io::Error),
@@ -67,6 +68,7 @@ impl error::Error for EncoderError {
     }
 }
 
+/// Alias for `Result<T, EncoderError>`.
 pub type EncoderResult<T> = Result<T, EncoderError>;
 
 fn write_string<W: Write + ?Sized>(writer: &mut W, s: &str) -> EncoderResult<()> {
@@ -109,13 +111,17 @@ fn encode_array<W: Write + ?Sized>(writer: &mut W, arr: &[Bson]) -> EncoderResul
     Ok(())
 }
 
+/// Attempt to encode a `Document` into a byte stream.
+///
+/// Can encode any type which is iterable as `(key: &str, value: &Bson)` pairs,
+/// which generally means most maps.
 pub fn encode_document
-    <'a, W: Write + ?Sized, D: IntoIterator<Item=(&'a String, &'a Bson)>>
+    <'a, S: AsRef<str> + 'a, W: Write + ?Sized, D: IntoIterator<Item=(&'a S, &'a Bson)>>
     (writer: &mut W, doc: D) -> EncoderResult<()>
 {
     let mut buf = Vec::new();
     for (key, val) in doc.into_iter() {
-        try!(encode_bson(&mut buf, key, val));
+        try!(encode_bson(&mut buf, key.as_ref(), val));
     }
 
     try!(write_i32(writer, (buf.len() + mem::size_of::<i32>() + mem::size_of::<u8>()) as i32));

src/lib.rs

@@ -22,7 +22,7 @@
 //! BSON is a binary format in which zero or more key/value pairs are stored as a single entity.
 //! We call this entity a document.
 //!
-//! This library supports Version 1.0 of BSON standard.
+//! This library supports version 1.0 of the [BSON standard](http://bsonspec.org/spec.html).
 //!
 //! ## Basic usage
 //!
@@ -46,7 +46,7 @@ extern crate rustc_serialize;
 extern crate chrono;
 extern crate byteorder;
 
-pub use self::bson::{Bson, ToBson, Document, Array};
+pub use self::bson::{Bson, Document, Array};
 pub use self::encoder::{encode_document, EncoderResult, EncoderError};
 pub use self::decoder::{decode_document, DecoderResult, DecoderError};
 

src/spec.rs

@@ -19,8 +19,7 @@
 // IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-//! BSON Specification Version 1.0
-/// http://bsonspec.org/spec.html
+//! Constants derived from the [BSON Specification Version 1.0](http://bsonspec.org/spec.html).
 
 use std::convert::From;
 
@@ -52,6 +51,9 @@ pub const BINARY_SUBTYPE_UUID_OLD                   : u8 = 0x03;
 pub const BINARY_SUBTYPE_UUID                       : u8 = 0x04;
 pub const BINARY_SUBTYPE_MD5                        : u8 = 0x05;
 
+/// All available BSON element types.
+///
+/// Not all element types are representable by the `Bson` type.
 #[repr(u8)]
 #[derive(Debug, Eq, PartialEq)]
 pub enum ElementType {
@@ -60,14 +62,14 @@ pub enum ElementType {
     EmbeddedDocument            = ELEMENT_TYPE_EMBEDDED_DOCUMENT,
     Array                       = ELEMENT_TYPE_ARRAY,
     Binary                      = ELEMENT_TYPE_BINARY,
-    #[warn(deprecated)]
+    /// Deprecated.
     Undefined                   = ELEMENT_TYPE_UNDEFINED,
     ObjectId                    = ELEMENT_TYPE_OBJECT_ID,
     Boolean                     = ELEMENT_TYPE_BOOLEAN,
     UtcDatetime                 = ELEMENT_TYPE_UTC_DATETIME,
     NullValue                   = ELEMENT_TYPE_NULL_VALUE,
     RegularExpression           = ELEMENT_TYPE_REGULAR_EXPRESSION,
-    #[warn(deprecated)]
+    /// Deprecated.
     DbPointer                   = ELEMENT_TYPE_DBPOINTER,
     JavaScriptCode              = ELEMENT_TYPE_JAVASCRIPT_CODE,
     Deprecated                  = ELEMENT_TYPE_DEPRECATED,
@@ -81,6 +83,7 @@ pub enum ElementType {
 }
 
 impl ElementType {
+    /// Attempt to convert from a `u8`.
     #[inline]
     pub fn from(tag: u8) -> Option<ElementType> {
         use self::ElementType::*;
@@ -110,6 +113,7 @@ impl ElementType {
     }
 }
 
+/// The available binary subtypes, plus a user-defined slot.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum BinarySubtype {
     Generic,