Docs site: Added BSON section

  JAVA-1704, JAVA-1705, JAVA-1706

Author: jyemin

docs/reference/content/reference/bson/documents.md

@@ -0,0 +1,86 @@
++++
+date = "2015-03-19T14:27:51-04:00"
+title = "Documents"
+[menu.main]
+  parent = "BSON"
+  weight = 50
+  pre = "<i class='fa'></i>"
++++
+
+## Documents
+
+The driver includes several classes and interfaces used for representing BSON documents.
+
+### BsonDocument
+
+Although generally not needed by users of the high-level driver API, the [BsonDocument]({{< apiref "org/bson/BsonDocument" >}}) class is 
+central to the way that documents are managed internally by the driver.  The BsonDocument class can represent dynamically structured 
+documents of any complexity with a type-safe API.  For instance, the document `{ a: "MongoDB", b: [ { c: 1 } ] }` can be constructed as a
+BsonDocument as follows:
+
+```java
+new BsonDocument().append("a", new BsonString("MongoDB"))
+                  .append("b", new BsonArray(Arrays.asList(new BsonInt32(1), new BsonInt32(2))));
+```
+
+The type safety comes from BsonDocument implementing `Map<String, BsonValue>`, so even built-in types like `int`, `String` and `List` must
+be wrapped in a sub-class of `BsonValue`.  For a complete list of BsonValue sub-types, please consult the 
+[API documentation]({{< apiref "org/bson/BsonValue" >}}). 
+
+### Document
+
+Most applications will use the [Document]({{< apiref "org/bson/Document" >}}) class instead.  Like BsonDocument, the 
+Document class can represent dynamically structured documents of any complexity; however, the typing is much looser, as Document 
+implements `Map<String, Object>`. As a result, the same document as above can be constructed using the Document class as follows:
+
+```java
+new Document().append("a", "MongoDB")
+              .append("b", Arrays.asList(1, 2));
+```
+
+There is less code to write, but runtime errors are possible if you inadvertently add an instance of an unsupported value type.  The most
+commonly used value types are: 
+   
+| BSON type | Java type               |
+|-----------|-------------------------|
+| Document  | org.bson.Document       |
+| Array     | java.util.List          |
+| Date      | java.util.Date          |
+| Boolean   | java.lang.Boolean       |
+| Double    | java.lang.Double        |
+| Int32     | java.lang.Integer       |
+| Int64     | java.lang.Long          |
+| String    | java.lang.String        |
+| Binary    | org.bson.types.Binary   |
+| ObjectId  | org.bson.types.ObjectId |
+| Null      | null                    |
+
+It is actually possible to change these mappings; the mechanism for doing so is currently beyond the scope of this reference.
+
+### DBObject
+
+Although not recommended for new applications, those upgrading from the 2.x driver series may continue to use the 
+[DBObject]({{< apiref "com/mongodb/DBObject" >}}) interface to represent BSON documents.  DBObject is similar to Document in that it 
+represents BSON values as `Object`, but it has a few shortcomings that were impossible to overcome:
+ 
+- it is an interface rather than a class, so it's API can not be extended without breaking binary compatibility
+- it doesn't actually implement `Map<String, Object>`
+- because it is an interface, a separate concrete class called [BasicDBObject]({{< apiref "com/mongodb/BasicDBObject" >}}) which implements 
+that interface, is required
+
+### Bson
+
+To tie these all together, the driver contains a small but powerful interface called [Bson]({{< apiref "org/bson/conversions/Bson" >}}). 
+Any class that represents a BSON document, whether included in the driver itself or from a third party, can implement this interface and 
+can then be used any place in the high-level API where a BSON document is required. The three classes discussed above all implement this 
+interface and so can be used interchangeably based on the needs of a given application.  For example:
+
+```java
+collection.find(new BsonDocument("x", new BsonInt32(1)));
+collection.find(new Document("x", 1));
+collection.find(new BasicDBObject("x", 1));
+```
+
+
+
+    

docs/reference/content/reference/bson/index.md

@@ -12,4 +12,5 @@ title = "BSON"
 The driver comprehensively supports [BSON](http://www.bsonspec.org), the data storage and network transfer format that MongoDB uses for 
 “documents". BSON, short for Binary [JSON](http://json.org/), is a binary-encoded serialization of JSON-like documents.
 
+- [Documents]({{< relref "documents.md" >}}): Documentation of the driver's support for BSON documents
 - [MongoDB Extended JSON]({{< relref "extended-json.md" >}}): Documentation of the driver's support for MongoDB Extended JSON