RUST-438 Add more detailed documentation examples (#176)

Author: patrickfreed

README.md

@@ -7,9 +7,20 @@
 
 Encoding and decoding support for BSON in Rust
 
+## Index
+- [Overview of BSON Format](#overview-of-bson-format)
+- [Usage](#usage)
+    - [BSON Values](#bson-values)
+    - [BSON Documents](#bson-documents)
+    - [Modeling BSON with strongly typed data structures](#modeling-bson-with-strongly-typed-data-structures)
+- [Breaking Changes](#breaking-changes)
+- [Contributing](#contributing)
+- [Running the Tests](#running-the-tests)
+- [Continuous Integration](#continuous-integration)
+
 ## Useful links
 - [API Documentation](https://docs.rs/bson/)
-- [Serde](https://serde.rs/)
+- [Serde Documentation](https://serde.rs/)
 
 ## Installation
 This crate works with Cargo and can be found on
@@ -20,53 +31,164 @@ This crate works with Cargo and can be found on
 bson = "0.14"
 ```
 
+## Overview of BSON Format
+
+BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents.
+Like JSON, BSON supports the embedding of documents and arrays within other documents
+and arrays. BSON also contains extensions that allow representation of data types that
+are not part of the JSON spec. For example, BSON has a datetime type and a binary data type.
+
+```text
+// JSON equivalent
+{"hello": "world"}
+
+// BSON encoding
+\x16\x00\x00\x00                   // total document size
+\x02                               // 0x02 = type String
+hello\x00                          // field name
+\x06\x00\x00\x00world\x00          // field value
+\x00                               // 0x00 = type EOO ('end of object')
+```
+
+BSON is the primary data representation for [MongoDB](https://www.mongodb.com/), and this crate is used in the
+[`mongodb`](https://docs.rs/mongodb/0.10.0/mongodb/) driver crate in its API and implementation.
+
+For more information about BSON itself, see [bsonspec.org](http://bsonspec.org).
+
 ## Usage
 
-Prepare your struct for Serde serialization:
+### BSON values
+
+Many different types can be represented as a BSON value, including 32-bit and 64-bit signed
+integers, 64 bit floating point numbers, strings, datetimes, embedded documents, and more. To
+see a full list of possible BSON values, see the [BSON specification](http://bsonspec.org/spec.html). The various
+possible BSON values are modeled in this crate by the [`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html) enum.
+
+#### Creating [`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html) instances
+
+[`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html) values can be instantiated directly or via the
+[`bson!`](https://docs.rs/bson/latest/bson/macro.bson.html) macro:
 
 ```rust
-#[derive(Serialize, Deserialize, Debug)]
-pub struct Person {
-    #[serde(rename = "_id")]  // Use MongoDB's special primary key field name when serializing 
-    pub id: bson::oid::ObjectId,
-    pub name: String,
-    pub age: i32
-}
+let string = Bson::String("hello world".to_string());
+let int = Bson::I32(5);
+let array = Bson::Array(vec![Bson::I32(5), Bson::Boolean(false)]);
+
+let string: Bson = "hello world".into();
+let int: Bson = 5i32.into();
+
+let string = bson!("hello world");
+let int = bson!(5);
+let array = bson!([5, false]);
 ```
+[`bson!`](https://docs.rs/bson/latest/bson/macro.bson.html) has supports both array and object literals, and it automatically converts any values specified to [`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html), provided they are `Into<Bson>`.
+
+#### [`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html) value unwrapping
 
-Serialize the struct:
+[`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html) has a number of helper methods for accessing the underlying native Rust types. These helpers can be useful in circumstances in which the specific type of a BSON value
+is known ahead of time.
 
+e.g.:
 ```rust
-use bson;
+let value = Bson::I32(5);
+let int = value.as_i32(); // Some(5)
+let bool = value.as_bool(); // None
 
-let person = Person {
-    id: "12345",
-    name: "Emma",
-    age: 3
-};
+let value = bson!([true]);
+let array = value.as_array(); // Some(&Vec<Bson>)
+```
 
-let serialized_person = bson::to_bson(&person)?;  // Serialize
+### BSON documents
 
-if let bson::Bson::Document(document) = serialized_person {
-    mongoCollection.insert_one(document, None)?;  // Insert into a MongoDB collection
-} else {
-    println!("Error converting the BSON object into a MongoDB document");
-}
+BSON documents are ordered maps of UTF-8 encoded strings to BSON values. They are logically similar to JSON objects in that they can contain subdocuments, arrays, and values of several different types. This crate models BSON documents via the
+[`Document`](https://docs.rs/bson/latest/bson/document/struct.Document.html) struct.
+
+#### Creating [`Document`](https://docs.rs/bson/latest/bson/document/struct.Document.html)s
+
+[`Document`](https://docs.rs/bson/latest/bson/document/struct.Document.html)s can be created directly either from a byte
+reader containing BSON data or via the `doc!` macro:
+```rust
+let mut bytes = hex::decode("0C0000001069000100000000").unwrap();
+let doc = Document::decode(&mut bytes.as_slice()).unwrap(); // { "i": 1 }
+
+let doc = doc! {
+   "hello": "world",
+   "int": 5,
+   "subdoc": { "cat": true },
+};
 ```
+[`doc!`](https://docs.rs/bson/latest/bson/macro.doc.html) works similarly to [`bson!`](https://docs.rs/bson/latest/bson/macro.bson.html), except that it always
+returns a [`Document`](https://docs.rs/bson/latest/bson/document/struct.Document.html) rather than a [`Bson`](https://docs.rs/bson/latest/bson/enum.Bson.html).
+
+#### [`Document`](https://docs.rs/bson/latest/bson/document/struct.Document.html) member access
 
-Deserialize the struct:
+[`Document`](https://docs.rs/bson/latest/bson/document/struct.Document.html) has a number of methods on it to facilitate member
+access:
 
 ```rust
-use bson::doc;
+let doc = doc! {
+   "string": "string",
+   "bool": true,
+   "i32": 5,
+   "doc": { "x": true },
+};
 
-// Read the document from a MongoDB collection
-let person_document = mongoCollection.find_one(Some(doc! { "_id":  bson::oid::ObjectId::with_string("12345").expect("Id not valid") }), None)?
-    .expect("Document not found");
+// attempt get values as untyped Bson
+let none = doc.get("asdfadsf"); // None
+let value = doc.get("string"); // Some(&Bson::String("string"))
 
-// Deserialize the document into a Person instance
-let person = bson::from_bson(bson::Bson::Document(person_document))?
+// attempt to get values with explicit typing
+let string = doc.get_str("string"); // Ok("string")
+let subdoc = doc.get_document("doc"); // Some(Document({ "x": true }))
+let error = doc.get_i64("i32"); // Err(...)
 ```
 
+### Modeling BSON with strongly typed data structures
+
+While it is possible to work with documents and BSON values directly, it will often introduce a
+lot of boilerplate for verifying the necessary keys are present and their values are the correct
+types. [`serde`](https://serde.rs/) provides a powerful way of mapping BSON data into Rust data structures largely
+automatically, removing the need for all that boilerplate.
+
+e.g.:
+```rust
+#[derive(Serialize, Deserialize)]
+struct Person {
+    name: String,
+    age: u8,
+    phones: Vec<String>,
+}
+
+fn typed_example() {
+    // Some BSON input data as a `Bson`.
+    let bson_data: Bson = bson!({
+        "name": "John Doe",
+        "age": 43,
+        "phones": [
+            "+44 1234567",
+            "+44 2345678"
+        ]
+    });
+
+    // Deserialize the Person struct from the BSON data, automatically
+    // verifying that the necessary keys are present and that they are of
+    // the correct types.
+    let mut person: Person = bson::from_bson(bson_data).unwrap();
+
+    // Do things just like with any other Rust data structure.
+    println!("Redacting {}'s record.", person.name);
+    person.name = "REDACTED".to_string();
+
+    // Get a serialized version of the input data as a `Bson`.
+    let redacted_bson = bson::to_bson(&person).unwrap();
+}
+```
+
+Any types that implement `Serialize` and `Deserialize` can be used in this way. Doing so helps
+separate the "business logic" that operates over the data from the (de)serialization logic that
+translates the data to/from its serialized form. This can lead to more clear and concise code
+that is also less error prone.
+
 ## Breaking Changes
 
 In the BSON specification, _unsigned integer types_ are unsupported; for example, `u32`. In the older version of this crate (< `v0.8.0`), if you uses `serde` to serialize _unsigned integer types_ into BSON, it will store them with `Bson::FloatingPoint` type. From `v0.8.0`, we removed this behavior and simply returned an error when you want to serialize _unsigned integer types_ to BSON. [#72](https://github.com/zonyitoo/bson-rs/pull/72)