RUST-252 Fully document driver with intra-docs links (#97)

Author: saghm

src/client/auth/mod.rs

@@ -1,3 +1,6 @@
+//! Contains the types needed to specify the auth configuration for a
+//! [`Client`](struct.Client.html).
+
 mod scram;
 #[cfg(test)]
 mod test;

src/client/mod.rs

@@ -38,9 +38,8 @@ const DEFAULT_SERVER_SELECTION_TIMEOUT: Duration = Duration::from_secs(30);
 /// so it can safely be shared across threads. For example:
 ///
 /// ```rust
-/// 
 /// # use mongodb::{Client, error::Result};
-///
+/// #
 /// # fn start_workers() -> Result<()> {
 /// let client = Client::with_uri_str("mongodb://example.com")?;
 ///
@@ -78,7 +77,8 @@ impl Client {
     /// Creates a new `Client` connected to the cluster specified by `uri`. `uri` must be a valid
     /// MongoDB connection string.
     ///
-    /// See the documentation on ClientOptions::parse for more details.
+    /// See the documentation on
+    /// [`ClientOptions::parse`](options/struct.ClientOptions.html#method.parse) for more details.
     pub fn with_uri_str(uri: &str) -> Result<Self> {
         let options = ClientOptions::parse(uri)?;
 
@@ -104,17 +104,17 @@ impl Client {
         }
     }
 
-    /// Gets the read preference of the `Client`.
+    /// Gets the default selection criteria the `Client` uses for operations..
     pub fn selection_criteria(&self) -> Option<&SelectionCriteria> {
         self.inner.options.selection_criteria.as_ref()
     }
 
-    /// Gets the read concern of the `Client`.
+    /// Gets the default read concern the `Client` uses for operations.
     pub fn read_concern(&self) -> Option<&ReadConcern> {
         self.inner.options.read_concern.as_ref()
     }
 
-    /// Gets the write concern of the `Client`.
+    /// Gets the default write concern the `Client` uses for operations.
     pub fn write_concern(&self) -> Option<&WriteConcern> {
         self.inner.options.write_concern.as_ref()
     }
@@ -139,11 +139,13 @@ impl Client {
         Database::new(self.clone(), name, Some(options))
     }
 
+    /// Gets information about each database present in the cluster the Client is connected to.
     pub fn list_databases(&self, filter: impl Into<Option<Document>>) -> Result<Vec<Document>> {
         let op = ListDatabases::new(filter.into(), false);
         self.execute_operation(&op, None)
     }
 
+    /// Gets the names of the databases present in the cluster the Client is connected to.
     pub fn list_database_names(&self, filter: impl Into<Option<Document>>) -> Result<Vec<String>> {
         let op = ListDatabases::new(filter.into(), true);
         match self.execute_operation(&op, None) {

src/client/options/mod.rs

@@ -51,9 +51,15 @@ lazy_static! {
     };
 }
 
+/// A hostname:port address pair.
 #[derive(Clone, Debug, Eq)]
 pub struct StreamAddress {
+    /// The hostname of the address.
     pub hostname: String,
+
+    /// The port of the address.
+    ///
+    /// The default is 27017.
     pub port: Option<u16>,
 }
 
@@ -155,7 +161,7 @@ impl fmt::Display for StreamAddress {
     }
 }
 
-/// Contains the options that can be used to create a new Client.
+/// Contains the options that can be used to create a new [`Client`](../struct.Client.html).
 #[derive(Clone, Derivative, TypedBuilder)]
 #[derivative(Debug, PartialEq)]
 pub struct ClientOptions {
@@ -351,6 +357,8 @@ struct ClientOptionsParser {
     original_uri: String,
 }
 
+/// Specifies whether TLS configuration should be used with the operations that the
+/// [`Client`](../struct.Client.html) performs.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Tls {
     Enabled(TlsOptions),
@@ -369,14 +377,27 @@ impl From<TlsOptions> for Option<Tls> {
     }
 }
 
+/// Specifies the TLS configuration that the [`Client`](../struct.Client.html) should use.
 #[derive(Clone, Debug, Default, PartialEq, TypedBuilder)]
 pub struct TlsOptions {
+    /// Whether or not the [`Client`](../struct.Client.html) should return an error if the server
+    /// presents an invalid certificate. This setting should _not_ be set to `true` in
+    /// production; it should only be used for testing.
+    ///
+    /// The default value is to error when the server presents an invalid certificate.
     #[builder(default)]
     pub allow_invalid_certificates: Option<bool>,
 
+    /// The path to the CA file that the [`Client`](../struct.Client.html) should use for TLS. If
+    /// none is specified, then the driver will use the Mozilla root certificates from the
+    /// `webpki-roots` crate.
     #[builder(default)]
     pub ca_file_path: Option<String>,
 
+    /// The path to the certificate file that the [`Client`](../struct.Client.html) should present
+    /// to the server to verify its identify. If none is specified, then the
+    /// [`Client`](../struct.Client.html) will not attempt to verify its identity to the
+    /// server.
     #[builder(default)]
     pub cert_key_file_path: Option<String>,
 }

src/cmap/test/event.rs

@@ -2,7 +2,7 @@ use std::sync::{Arc, RwLock};
 
 use serde::{de::Unexpected, Deserialize, Deserializer};
 
-use crate::event::cmap::*;
+use crate::{event::cmap::*, options::StreamAddress};
 
 #[derive(Clone, Debug)]
 pub struct EventHandler {

src/coll/mod.rs

@@ -30,8 +30,9 @@ use crate::{
 
 /// `Collection` is the client-side abstraction of a MongoDB Collection. It can be used to
 /// perform collection-level operations such as CRUD operations. A `Collection` can be obtained
-/// through a `Database` by calling either `Database::collection` or
-/// `Database::collection_with_options`.
+/// through a [`Database`](struct.Database.html) by calling either
+/// [`Database::collection`](struct.Database.html#method.collection) or
+/// [`Database::collection_with_options`](struct.Database.html#method.collection_with_options).
 ///
 /// `Collection` uses [`std::sync::Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html) internally,
 /// so it can safely be shared across threads. For example:
@@ -184,8 +185,8 @@ impl Collection {
 
     /// Gets the number of documents matching `filter`.
     ///
-    /// Note that using `Collection::estimated_document_count` is recommended instead of this method
-    /// is most cases.
+    /// Note that using [`Collection::estimated_document_count`](#method.estimated_document_count)
+    /// is recommended instead of this method is most cases.
     pub fn count_documents(
         &self,
         filter: impl Into<Option<Document>>,

src/coll/options.rs

@@ -12,8 +12,8 @@ use crate::{
     selection_criteria::SelectionCriteria,
 };
 
-/// These are the valid options for creating a `Collection` with
-/// `Database::collection_with_options`.
+/// These are the valid options for creating a [`Collection`](../struct.Collection.html) with
+/// [`Database::collection_with_options`](../struct.Database.html#method.collection_with_options).
 #[derive(Debug, Default, TypedBuilder)]
 pub struct CollectionOptions {
     /// The default read preference for operations.
@@ -29,7 +29,9 @@ pub struct CollectionOptions {
     pub write_concern: Option<WriteConcern>,
 }
 
-/// Specifies whether a `Collection::find_one_and_replace` and `Collection::find_one_and_update`
+/// Specifies whether a
+/// [`Collection::find_one_and_replace`](../struct.Collection.html#method.find_one_and_replace) and
+/// [`Collection::find_one_and_update`](../struct.Collection.html#method.find_one_and_update)
 /// operation should return the document before or after modification.
 #[derive(Debug)]
 pub enum ReturnDocument {
@@ -73,7 +75,8 @@ pub enum CursorType {
     TailableAwait,
 }
 
-/// Specifies the options to a `Collection::insert_one` operation.
+/// Specifies the options to a
+/// [`Collection::insert_one`](../struct.Collection.html#method.insert_one) operation.
 #[derive(Clone, Debug, Default, TypedBuilder)]
 pub struct InsertOneOptions {
     /// Opt out of document-level validation.
@@ -85,7 +88,8 @@ pub struct InsertOneOptions {
     pub write_concern: Option<WriteConcern>,
 }
 
-/// Specifies the options to a `Collection::insert_many` operation.
+/// Specifies the options to a
+/// [`Collection::insert_many`](../struct.Collection.html#method.insert_many) operation.
 #[skip_serializing_none]
 #[derive(Clone, Debug, Default, TypedBuilder, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -154,7 +158,9 @@ impl From<Vec<Document>> for UpdateModifications {
     }
 }
 
-/// Specifies the options to a `Collection::update_one` or `Collection::update_many` operation.
+/// Specifies the options to a
+/// [`Collection::update_one`](../struct.Collection.html#method.update_one) or
+/// [`Collection::update_many`](../struct.Collection.html#method.update_many) operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct UpdateOptions {
     /// A set of filters specifying to which array elements an update should apply.
@@ -204,7 +210,8 @@ impl UpdateOptions {
     }
 }
 
-/// Specifies the options to a `Collection::replace_one` operation.
+/// Specifies the options to a
+/// [`Collection::replace_one`](../struct.Collection.html#method.replace_one) operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct ReplaceOptions {
     /// Opt out of document-level validation.
@@ -233,7 +240,9 @@ pub struct ReplaceOptions {
     pub write_concern: Option<WriteConcern>,
 }
 
-/// Specifies the options to a `Collection::delete_one` or `Collection::delete_many` operation.
+/// Specifies the options to a
+/// [`Collection::delete_one`](../struct.Collection.html#method.delete_one) or
+/// [`Collection::delete_many`](../struct.Collection.html#method.delete_many) operation.
 #[serde_with::skip_serializing_none]
 #[derive(Debug, Default, TypedBuilder, Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -250,7 +259,9 @@ pub struct DeleteOptions {
     pub write_concern: Option<WriteConcern>,
 }
 
-/// Specifies the options to a `Collection::find_one_and_delete` operation.
+/// Specifies the options to a
+/// [`Collection::find_one_and_delete`](../struct.Collection.html#method.find_one_and_delete)
+/// operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct FindOneAndDeleteOptions {
     /// The maximum amount of time to allow the query to run.
@@ -280,7 +291,9 @@ pub struct FindOneAndDeleteOptions {
     pub collation: Option<Collation>,
 }
 
-/// Specifies the options to a `Collection::find_one_and_replace` operation.
+/// Specifies the options to a
+/// [`Collection::find_one_and_replace`](../struct.Collection.html#method.find_one_and_replace)
+/// operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct FindOneAndReplaceOptions {
     /// Opt out of document-level validation.
@@ -322,13 +335,16 @@ pub struct FindOneAndReplaceOptions {
     pub collation: Option<Collation>,
 }
 
-/// Specifies the options to a `Collection::find_one_and_update` operation.
+/// Specifies the options to a
+/// [`Collection::find_one_and_update`](../struct.Collection.html#method.find_one_and_update)
+/// operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct FindOneAndUpdateOptions {
     /// A set of filters specifying to which array elements an update should apply.
     ///
     /// See the documentation [here](https://docs.mongodb.com/manual/reference/command/update/) for
-    /// more information on array filters.#[builder(default)]
+    /// more information on array filters.
+    #[builder(default)]
     pub array_filters: Option<Vec<Document>>,
 
     /// Opt out of document-level validation.
@@ -370,7 +386,8 @@ pub struct FindOneAndUpdateOptions {
     pub collation: Option<Collation>,
 }
 
-/// Specifies the options to a `Collection::aggregate` operation.
+/// Specifies the options to a [`Collection::aggregate`](../struct.Collection.html#method.aggregate)
+/// operation.
 #[skip_serializing_none]
 #[serde(rename_all = "camelCase")]
 #[derive(Clone, Debug, Default, TypedBuilder, Serialize)]
@@ -452,7 +469,8 @@ pub struct AggregateOptions {
     pub write_concern: Option<WriteConcern>,
 }
 
-/// Specifies the options to a `Collection::count_documents` operation.
+/// Specifies the options to a
+/// [`Collection::count_documents`](../struct.Collection.html#method.count_documents) operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct CountOptions {
     /// The index to use for the operation.
@@ -482,7 +500,13 @@ pub struct CountOptions {
     pub collation: Option<Collation>,
 }
 
-/// Specifies the options to a `Collection::estimated_document_count` operation.
+// rustfmt tries to split the link up when it's all on one line, which breaks the link, so we wrap
+// the link contents in whitespace to get it to render correctly.
+//
+/// Specifies the options to a
+/// [
+///  `Collection::estimated_document_count`
+/// ](../struct.Collection.html#method.estimated_document_count) operation.
 #[serde_with::skip_serializing_none]
 #[derive(Debug, Default, TypedBuilder, Serialize, Clone)]
 #[serde(rename_all = "camelCase")]
@@ -498,16 +522,20 @@ pub struct EstimatedDocumentCountOptions {
     )]
     pub max_time: Option<Duration>,
 
+    /// The criteria used to select a server for this operation.
+    ///
+    /// If none specified, the default set on the collection will be used.
     #[builder(default)]
     #[serde(skip_serializing)]
     pub selection_criteria: Option<SelectionCriteria>,
 
-    /// The level of the read concern
+    /// The level of the read concern.
     #[builder(default)]
     pub read_concern: Option<ReadConcern>,
 }
 
-/// Specifies the options to a `Collection::distinct` operation.
+/// Specifies the options to a [`Collection::distinct`](../struct.Collection.html#method.distinct)
+/// operation.
 #[serde_with::skip_serializing_none]
 #[derive(Debug, Default, TypedBuilder, Serialize, Clone)]
 #[serde(rename_all = "camelCase")]
@@ -523,11 +551,14 @@ pub struct DistinctOptions {
     )]
     pub max_time: Option<Duration>,
 
+    /// The criteria used to select a server for this operation.
+    ///
+    /// If none specified, the default set on the collection will be used.
     #[builder(default)]
     #[serde(skip_serializing)]
     pub selection_criteria: Option<SelectionCriteria>,
 
-    /// The level of the read concern
+    /// The level of the read concern.
     #[builder(default)]
     pub read_concern: Option<ReadConcern>,
 
@@ -539,7 +570,8 @@ pub struct DistinctOptions {
     pub collation: Option<Collation>,
 }
 
-/// Specifies the options to a `Collection::find` operation.
+/// Specifies the options to a [`Collection::find`](../struct.Collection.html#method.find)
+/// operation.
 #[skip_serializing_none]
 #[derive(Debug, Default, TypedBuilder, Serialize)]
 #[serde(rename_all = "camelCase")]
@@ -692,7 +724,8 @@ where
     }
 }
 
-/// Specifies the options to a `Collection::find_one` operation.
+/// Specifies the options to a [`Collection::find_one`](../struct.Collection.html#method.find_one)
+/// operation.
 #[derive(Debug, Default, TypedBuilder)]
 pub struct FindOneOptions {
     /// If true, partial results will be returned from a mongos rather than an error being
@@ -771,7 +804,8 @@ pub struct IndexModel {
     pub options: Option<Document>,
 }
 
-/// Specifies the options to a `Collection::drop` operation.
+/// Specifies the options to a [`Collection::drop`](../struct.Collection.html#method.drop)
+/// operation.
 #[derive(Debug, Default, TypedBuilder, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DropCollectionOptions {

src/concern.rs

@@ -96,7 +96,7 @@ pub struct WriteConcern {
     pub journal: Option<bool>,
 }
 
-/// The type of the `w` field in a write concern.
+/// The type of the `w` field in a [`WriteConcern`](struct.WriteConcern.html).
 #[derive(Clone, Debug, PartialEq)]
 pub enum Acknowledgment {
     /// Requires acknowledgement that the write has reached the specified number of nodes.