RUST-736 Update driver documentation for 2.0 release (#437)

Author: patrickfreed

.evergreen/check-rustdoc.sh

@@ -3,6 +3,4 @@
 set -o errexit
 
 . ~/.cargo/env
-cargo rustdoc -- -D warnings
-cargo rustdoc --no-default-features --features async-std-runtime -- -D warnings
-cargo rustdoc --no-default-features --features sync -- -D warnings
+cargo +nightly rustdoc -p bson --all-features -- --cfg docsrs -D warnings

README.md

@@ -9,6 +9,7 @@ This repository contains the officially supported MongoDB Rust driver, a client
     - [Importing](#importing)
         - [Configuring the async runtime](#configuring-the-async-runtime)
         - [Enabling the sync API](#enabling-the-sync-api)
+        - [All feature flags](#all-feature-flags)
 - [Example Usage](#example-usage)
     - [Using the async API](#using-the-async-api)
         - [Connecting to a MongoDB deployment](#connecting-to-a-mongodb-deployment)
@@ -58,6 +59,17 @@ features = ["sync"]
 ```
 **Note:** if the sync API is enabled, the async-specific types will be privatized (e.g. `mongodb::Client`). The sync-specific types can be imported from `mongodb::sync` (e.g. `mongodb::sync::Client`).
 
+### All Feature Flags
+
+| Feature             | Description                                                                                                                           | Extra dependencies                  | Default |
+|:--------------------|:--------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------|:--------|
+| `tokio-runtime`     | Enable support for the `tokio` async runtime                                                                                          | `tokio` 1.0 with the `full` feature | yes     |
+| `async-std-runtime` | Enable support for the `async-std` runtime                                                                                            | `async-std` 1.0                     | no      |
+| `sync`              | Expose the synchronous API (`mongodb::sync`). This flag cannot be used in conjunction with either of the async runtime feature flags. | `async-std` 1.0                     | no      |
+| `aws-auth`          | Enable support for the MONGODB-AWS authentication mechanism.                                                                          | `reqwest` 0.11                      | no      |
+| `bson-uuid-0_8`     | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API of the re-exported `bson` crate.                    | `uuid` 0.8                          | no      |
+| `bson-chrono-0_4`   | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API of the re-exported `bson` crate.                | n/a                                 | no      |
+
 ## Example Usage
 Below are simple examples of using the driver. For more specific examples and the API reference, see the driver's [docs.rs page](https://docs.rs/mongodb/2.0.0-beta.3).
 

src/coll/mod.rs

@@ -58,9 +58,19 @@ use crate::{
 /// [`Database::collection`](struct.Database.html#method.collection) or
 /// [`Database::collection_with_options`](struct.Database.html#method.collection_with_options).
 ///
+/// A [`Collection`] can be parameterized with any type that implements the
+/// `Serialize` and `Deserialize` traits from the [`serde`](https://serde.rs/) crate. This includes but
+/// is not limited to just `Document`. The various methods that accept or return instances of the
+/// documents in the collection will accept/return instances of the generic parameter (e.g.
+/// [`Collection::insert_one`] accepts it as an argument, [`Collection::find_one`] returns an
+/// `Option` of it). It is recommended to define types that model your data which you can
+/// parameterize your [`Collection`]s with instead of `Document`, since doing so eliminates a lot of
+/// boilerplate deserialization code and is often more performant.
+///
 /// `Collection` uses [`std::sync::Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html) internally,
-/// so it can safely be shared across threads or async tasks. For example:
+/// so it can safely be shared across threads or async tasks.
 ///
+/// # Example
 /// ```rust
 /// # use mongodb::{
 /// #     bson::doc,
@@ -76,14 +86,24 @@ use crate::{
 /// # use mongodb::Client;
 /// #
 /// # let client = Client::with_uri_str("mongodb://example.com").await?;
-/// let coll = client.database("items").collection("in_stock");
+/// use serde::{Deserialize, Serialize};
+///
+/// /// Define a type that models our data.
+/// #[derive(Clone, Debug, Deserialize, Serialize)]
+/// struct Item {
+///     id: u32,
+/// }
+///
+/// // Parameterize our collection with the model.
+/// let coll = client.database("items").collection::<Item>("in_stock");
 ///
 /// for i in 0..5 {
 ///     let coll_ref = coll.clone();
 ///
+///     // Spawn several tasks that operate on the same collection concurrently.
 ///     task::spawn(async move {
-///         // Perform operations with `coll_ref`. For example:
-///         coll_ref.insert_one(doc! { "x": i }, None).await;
+///         // Perform operations with `coll_ref` that work with directly our model.
+///         coll_ref.insert_one(Item { id: i }, None).await;
 ///     });
 /// }
 /// #

src/db/mod.rs

@@ -130,19 +130,25 @@ impl Database {
         self.inner.write_concern.as_ref()
     }
 
-    /// Gets a handle to a collection with type `T` specified by `name` of the database. The
-    /// `Collection` options (e.g. read preference and write concern) will default to those of the
-    /// `Database`.
+    /// Gets a handle to a collection in this database with the provided name. The
+    /// [`Collection`] options (e.g. read preference and write concern) will default to those of
+    /// this [`Database`].
+    ///
+    /// For more information on how the generic parameter `T` is used, check out the [`Collection`]
+    /// documentation.
     ///
     /// This method does not send or receive anything across the wire to the database, so it can be
     /// used repeatedly without incurring any costs from I/O.
     pub fn collection<T>(&self, name: &str) -> Collection<T> {
         Collection::new(self.clone(), name, None)
     }
 
-    /// Gets a handle to a collection with type `T` specified by `name` in the cluster the `Client`
-    /// is connected to. Operations done with this `Collection` will use the options specified by
-    /// `options` by default and will otherwise default to those of the `Database`.
+    /// Gets a handle to a collection in this database with the provided name.
+    /// Operations done with this `Collection` will use the options specified by
+    /// `options` and will otherwise default to those of this [`Database`].
+    ///
+    /// For more information on how the generic parameter `T` is used, check out the [`Collection`]
+    /// documentation.
     ///
     /// This method does not send or receive anything across the wire to the database, so it can be
     /// used repeatedly without incurring any costs from I/O.