From dd4b3b7f4f9bff8a0e7ab78a324ff86c7df11065 Mon Sep 17 00:00:00 2001
From: Thijs Cadier <thijs@appsignal.com>
Date: Sun, 27 Dec 2015 15:36:24 +0100
Subject: [PATCH] Documentation for Database

---
 src/collection.rs |  8 ++++----
 src/database.rs   | 26 +++++++++++++++-----------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/src/collection.rs b/src/collection.rs
index e969592..cf345e3 100644
--- a/src/collection.rs
+++ b/src/collection.rs
@@ -1,6 +1,6 @@
-//! Access to a MongoDB collection
+//! Access to a MongoDB collection.
 //!
-//! Collection is the main type used when accessing collections.
+//! `Collection` is the main type used when accessing collections.
 
 use std::ptr;
 use std::ffi::CStr;
@@ -34,7 +34,7 @@ pub enum CreatedBy<'a> {
 
 /// Provides access to a collection for most CRUD operations, I.e. insert, update, delete, find, etc.
 ///
-/// A collection instance can be created by calling `get_collection` on a `Client` or `Database`
+/// A collection instance can be created by calling `get_collection` or `take_database` on a `Client` or `Database`
 /// instance.
 pub struct Collection<'a> {
     _created_by: CreatedBy<'a>,
@@ -210,7 +210,7 @@ impl<'a> Collection<'a> {
         }
     }
 
-    /// Execute a command on the collection
+    /// Execute a command on the collection.
     /// This is performed lazily and therefore requires calling `next` on the resulting cursor.
     pub fn command(
         &'a self,
diff --git a/src/database.rs b/src/database.rs
index 2563f9e..bf97f31 100644
--- a/src/database.rs
+++ b/src/database.rs
@@ -1,3 +1,5 @@
+//! Access to a MongoDB database.
+
 use std::ffi::{CString,CStr};
 use std::borrow::Cow;
 use std::ptr;
@@ -14,19 +16,25 @@ use super::collection;
 use super::collection::Collection;
 use super::cursor;
 use super::cursor::Cursor;
+use super::read_prefs::ReadPrefs;
 use flags::FlagsValue;
 
+#[doc(hidden)]
 pub enum CreatedBy<'a> {
     BorrowedClient(&'a Client<'a>),
     OwnedClient(Client<'a>)
 }
 
+/// Provides access to a MongoDB database.
+///
+/// A database instance can be created by calling `get_database` or `take_database` on a `Client` instance.
 pub struct Database<'a> {
     _created_by: CreatedBy<'a>,
     inner:   *mut bindings::mongoc_database_t
 }
 
 impl<'a> Database<'a> {
+    #[doc(ignore)]
     pub fn new(
         created_by: CreatedBy<'a>,
         inner: *mut bindings::mongoc_database_t
@@ -38,9 +46,8 @@ impl<'a> Database<'a> {
         }
     }
 
-    /// Execute a command on the database
-    ///
-    /// See: http://api.mongodb.org/c/current/mongoc_database_command.html
+    /// Execute a command on the database.
+    /// This is performed lazily and therefore requires calling `next` on the resulting cursor.
     pub fn command(
         &'a self,
         command: Document,
@@ -82,19 +89,14 @@ impl<'a> Database<'a> {
         ))
     }
 
-    /// Simplified version of command that returns the first document
-    ///
-    /// See: http://api.mongodb.org/c/current/mongoc_database_command_simple.html
+    /// Simplified version of `command` that returns the first document immediately.
     pub fn command_simple(
         &'a self,
         command: Document,
-        options: Option<&CommandAndFindOptions>
+        read_prefs: Option<&ReadPrefs>
     ) -> Result<Document> {
         assert!(!self.inner.is_null());
 
-        let default_options = CommandAndFindOptions::default();
-        let options         = options.unwrap_or(&default_options);
-
         // Bsonc to store the reply
         let mut reply = Bsonc::new();
         // Empty error that might be filled
@@ -104,7 +106,7 @@ impl<'a> Database<'a> {
             bindings::mongoc_database_command_simple(
                 self.inner,
                 try!(Bsonc::from_document(&command)).inner(),
-                match options.read_prefs {
+                match read_prefs {
                     Some(ref prefs) => prefs.inner(),
                     None => ptr::null()
                 },
@@ -123,6 +125,7 @@ impl<'a> Database<'a> {
         }
     }
 
+    /// Create a new collection in this database.
     pub fn create_collection<S: Into<Vec<u8>>>(
         &self,
         name:    S,
@@ -179,6 +182,7 @@ impl<'a> Database<'a> {
         )
     }
 
+    /// Get the name of this database.
     pub fn get_name(&self) -> Cow<str> {
         let cstr = unsafe {
             CStr::from_ptr(bindings::mongoc_database_get_name(self.inner))