DOCSP-39852: Fluent API (#118)

Author: norareidy

source/faq.txt

@@ -134,7 +134,7 @@ and using the ``try_next()`` method to iterate over ``Actor`` instances causes a
    // Add setup code here 
 
    let my_coll: Collection<Actor> = client.database("db").collection("actors");
-   let mut cursor = my_coll.find(None, None).await?;
+   let mut cursor = my_coll.find(doc! {}).await?;
    while let Some(result) = cursor.try_next().await? {
         println!("{:?}", result);
     };
@@ -195,15 +195,15 @@ using the ``?`` operator while handling an insert operation result:
 .. code-block:: rust
    :copyable: true
 
-   let insert_one_result = my_coll.insert_one(doc, None).await?;
+   let insert_one_result = my_coll.insert_one(doc).await?;
 
 Alternatively, you can create a conditional to handle the unwrapped values of ``InsertOneResult``.
 The following code uses the ``match`` keyword to process the ``insert_one()`` result:
 
 .. code-block:: rust
    :copyable: true
 
-   let insert_one_result = my_coll.insert_one(doc, None).await;
+   let insert_one_result = my_coll.insert_one(doc).await;
 
    match insert_one_result {
       Ok(val) => {

source/fundamentals/collations.txt

@@ -96,10 +96,10 @@ You can define a collation by specifying a collation locale and other options in
 struct instance. To begin building a ``Collation`` instance, call the ``Collation::builder()``
 method.
 
-.. note:: Instantiating Options
+.. note:: Instantiating Structs
 
    The {+driver-short+} implements the Builder design pattern for the
-   creation of many different types, including ``Collation``. You can
+   creation of some struct types, including ``Collation``. You can
    use the ``builder()`` method to construct an instance of each type
    by chaining option builder methods.
 
@@ -181,9 +181,9 @@ Set a Collation on a Collection
 -------------------------------
 
 When you create a new collection, you can define the collation for future operations
-called on that collection. Set the collation by using the ``collation()`` function
-when creating a ``CreateCollectionOptions`` instance. Then, call the ``create_collection()``
-method with your options instance as a parameter.
+called on that collection. Set the collation by chaining the ``collation()`` function
+to the ``create_collection()`` method, passing your ``Collation`` instance as a parameter
+to ``collation()``.
 
 .. _rust-create-collection:
 
@@ -308,9 +308,10 @@ This example performs the following actions:
 
 - Sets the ``numeric_ordering`` collation option to ``true``, which ensures that values are sorted in
   numerical order rather than alphabetical order
-- Specifies a collation in a ``FindOptions`` instance, which overrides the collection's collation
 - Uses the ``find()`` method to return documents in which the value of the ``length`` field is greater
   than ``"1000"``
+- Specifies a collation by chaining the ``collation()`` method to the ``find()`` method, which overrides
+  the collection's collation
 
 .. io-code-block::
    :copyable: true

source/fundamentals/crud/compound-operations.txt

@@ -97,12 +97,11 @@ Modify Find and Delete Behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can optionally modify the behavior of the ``find_one_and_delete()``
-method by passing a ``FineOneAndDeleteOptions`` instance as a parameter.
-To use default values for each setting, specify the value ``None`` for
-the options parameter.
+method by chaining option builder methods to ``find_one_and_delete()``. These
+builder methods set ``FindOneAndDeleteOptions`` struct fields.
 
 The following table describes the options available in
-``FineOneAndDeleteOptions``:
+``FindOneAndDeleteOptions``:
 
 .. list-table::
    :widths: 30 70
@@ -175,13 +174,15 @@ The following table describes the options available in
 
 .. TODO add links to guides for relevant options
 
-The {+driver-short+} implements the Builder design pattern for the
-creation of a ``FindOneAndDeleteOptions`` instance. You can use the
-type's ``builder()`` method to construct an options instance by
-chaining option builder functions one at a time.
+.. note:: Setting Options
+   
+   You can set ``FindOneAndDeleteOptions`` fields by chaining option builder methods directly
+   to the ``find_one_and_delete()`` method call. If you're using an earlier version of the driver,
+   you must construct a ``FindOneAndDeleteOptions`` instance by chaining option builder methods
+   to the ``builder()`` method. Then, pass your options instance as a parameter to ``find_one_and_delete()``.
 
-The following code shows how to construct a ``FindOneAndDeleteOptions``
-instance and pass it to the ``find_one_and_delete()`` method:
+The following code shows how to set the ``comment`` field by chaining
+the ``comment()`` method to the ``find_one_and_delete()`` method:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/crud/compound.rs
    :start-after: begin-find-delete-options
@@ -236,12 +237,11 @@ Modify Find and Update Behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can optionally modify the behavior of the ``find_one_and_update()``
-method by passing a ``FindOneAndUpdateOptions`` instance as a parameter.
-To use default values for each setting, specify the value ``None`` for
-the options parameter.
+method by chaining option builder methods to ``find_one_and_update()``. These
+builder methods set ``FindOneAndUpdateOptions`` struct fields.
 
 The following table describes the options available in
-``FineOneAndDeleteOptions``:
+``FindOneAndUpdateOptions``:
 
 .. list-table::
    :widths: 30 70
@@ -343,13 +343,8 @@ The following table describes the options available in
 .. TODO add link to array updates page under option
 .. TODO add links to guides for relevant options
 
-The {+driver-short+} implements the Builder design pattern for the
-creation of a ``FindOneAndUpdateOptions`` instance. You can use the
-type's ``builder()`` method to construct an options instance by
-chaining option builder methods one at a time.
-
-The following code shows how to construct a ``FindOneAndUpdateOptions``
-instance and pass it to the ``find_one_and_update()`` method:
+The following code shows how to set the ``comment`` field by chaining
+the ``comment()`` method to the ``find_one_and_update()`` method:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/crud/compound.rs
    :start-after: begin-find-update-options
@@ -361,15 +356,15 @@ instance and pass it to the ``find_one_and_update()`` method:
 Find and Update Example
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-This example shows how to call the ``find_one_and_update()`` method with the
-following parameters:
+This example shows how to perform the following actions:
 
-- A query filter that matches a document where the value of ``school``
-  is ``"Aurora High School"``
-- An update document that sets the ``school`` field to ``"Durango High School"``
-  and increments the ``age`` field by ``1``
-- A ``FindOneAndUpdateOptions`` instance that returns the document
-  *after* the update
+- Call the ``find_one_and_update()`` method
+- Pass a query filter to ``find_one_and_update()`` that matches a document where the
+  value of ``school`` is ``"Aurora High School"``
+- Pass an update document to ``find_one_and_update()`` that sets the ``school`` field to
+  ``"Durango High School"`` and increments the ``age`` field by ``1``
+- Chain the ``return_document()`` method to ``find_one_and_update()`` to return
+  the matched document *after* the update
 
 .. io-code-block::
    :copyable: true
@@ -411,9 +406,8 @@ Modify Find and Replace Behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can optionally modify the behavior of the ``find_one_and_replace()``
-method by passing a ``FindOneAndReplaceOptions`` instance as a parameter.
-To use default values for each setting, specify the value ``None`` for
-the options parameter.
+method by chaining option builder methods to ``find_one_and_replace()``. These
+builder methods set ``FindOneAndReplaceOptions`` struct fields.
 
 The following table describes the options available in
 ``FindOneAndReplaceOptions``:
@@ -511,14 +505,9 @@ The following table describes the options available in
 
 .. TODO add link to array updates page under option
 .. TODO add links to guides for relevant options
-   
-The {+driver-short+} implements the Builder design pattern for the
-creation of a ``FindOneAndReplaceOptions`` instance. You can use the
-type's ``builder()`` method to construct an options instance by
-chaining option builder functions one at a time.
 
-The following code shows how to construct a ``FindOneAndReplaceOptions``
-instance and pass it to the ``find_one_and_replace()`` method:
+The following code shows how to set the ``comment`` field by chaining
+the ``comment()`` method to the ``find_one_and_replace()`` method:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/crud/compound.rs
    :start-after: begin-find-replace-options
@@ -530,15 +519,17 @@ instance and pass it to the ``find_one_and_replace()`` method:
 Find and Replace Example
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This example shows how to call the ``find_one_and_replace()`` method with the
-following parameters:
-
-- A query filter that matches a document where the value of ``name``
-  includes the string ``"Johnson"``
-- A replacement document that describes a new student
-- A ``FindOneAndReplaceOptions`` instance that returns the document
-  after replacement and projects only the ``name`` and ``school`` fields
-  in the output
+This example performs the following actions:
+
+- Calls the ``find_one_and_replace()`` method
+- Passes a query filter to ``find_one_and_replace()`` that matches a document
+  where the value of ``name`` includes the string ``"Johnson"``
+- Passes a replacement document to ``find_one_and_replace()`` that describes a new
+  student
+- Chains the ``return_document()`` method to ``find_one_and_replace()`` to return the document
+  after replacement
+- Chains the ``projection()`` method to ``find_one_and_replace()``to project only the ``name``
+  and ``school`` fields in the output
 
 .. io-code-block::
    :copyable: true

source/fundamentals/crud/read-operations/change-streams.txt

@@ -137,8 +137,9 @@ is ``"Wes Anderson"``, the preceding code produces the following output:
 Apply Aggregation Operators to your Change Stream
 -------------------------------------------------
 
-You can pass an aggregation pipeline as a parameter to the ``watch()`` method
-to specify which change events the change stream receives.
+You can chain the ``pipeline()`` method to the ``watch()`` method
+to specify which change events the change stream receives. Pass an
+aggregation pipeline as a parameter to ``pipeline()``.
 
 To learn which aggregation operators your MongoDB Server version supports, see
 :ref:`<change-stream-modify-output>` in the Server manual.
@@ -147,7 +148,7 @@ Example
 ~~~~~~~
 
 The following example creates an aggregation pipeline to filter for update
-operations. Then, the code passes the pipeline to the ``watch()`` method,
+operations. Then, the code passes the pipeline to the ``pipeline()`` method,
 configuring the change stream to only receive and print change events for
 update operations:
 
@@ -222,22 +223,10 @@ must perform the following actions:
 Create a Collection with Pre-Image and Post-Images Enabled
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To create a collection with the pre-image and post-image documents enabled,
-configure this option in a ``CreateCollectionOptions`` struct instance. To begin
-building a ``CreateCollectionOptions`` instance, call the ``CreateCollectionOptions::builder()``
-method.
-
-.. note:: Instantiating Options
-   
-   The {+driver-short+} implements the Builder design pattern for the
-   creation of many different types, including ``CreateCollectionOptions``. You
-   can use the ``builder()`` method to construct an instance of each type
-   by chaining option builder methods.
-
-When configuring your ``CreateCollectionOptions`` instance, you must use the
-``change_stream_pre_and_post_images()`` builder method. The following example
-uses this builder method to specify collection options and creates a
-collection for which pre- and post-images are available:
+To enable pre-image and post-image documents for your collection, use the
+``change_stream_pre_and_post_images()`` option builder method. The following example
+uses this builder method to specify collection options and creates a collection
+for which pre- and post-images are available:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/crud/watch.rs
    :language: rust
@@ -262,11 +251,7 @@ Pre-Image Configuration Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To configure a change stream that returns change events containing the pre-image,
-specify a ``ChangeStreamOptions`` struct instance. To begin building a ``ChangeStreamOptions``
-instance, call the ``ChangeStreamOptions::builder()`` method.
-
-When configuring your ``ChangeStreamOptions`` instance to return the pre-image document,
-you must use the ``full_document_before_change()`` builder method. The following example
+use the ``full_document_before_change()`` option builder method. The following example
 specifies change stream options and creates a change stream that returns pre-image
 documents:
 
@@ -277,7 +262,7 @@ documents:
    :end-before: end-pre
 
 The preceding example passes a value of ``FullDocumentBeforeChangeType::Required``
-to the ``full_document_before_change()`` builder method. This option configures the change
+to the ``full_document_before_change()`` option builder method. This method configures the change
 stream to require pre-images for replace, update, and delete change events. If the pre-image
 is not available, the driver raises an error.
 
@@ -297,11 +282,7 @@ Post-Image Configuration Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To configure a change stream that returns change events containing the post-image,
-specify a ``ChangeStreamOptions`` struct instance. To begin building a ``ChangeStreamOptions``
-instance, call the ``ChangeStreamOptions::builder()`` method.
-
-When configuring your ``ChangeStreamOptions`` instance to return the post-image document,
-you must use the ``full_document()`` builder method. The following example specifies change
+use the ``full_document()`` option builder method. The following example specifies change
 stream options and creates a change stream that returns post-image documents:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/crud/watch.rs
@@ -311,8 +292,8 @@ stream options and creates a change stream that returns post-image documents:
    :end-before: end-post
 
 The preceding example passes a value of ``FullDocument::WhenAvailable`` to the ``full_document()``
-builder method. This option configures the change stream to return post-images for replace, update,
-and delete change events if the post-image is available.
+option builder method. This method configures the change stream to return post-images for replace,
+update, and delete change events if the post-image is available.
 
 If you delete the document in which the value of ``name`` is ``"Todd Haynes"``, the
 change event produces the following output:

source/fundamentals/crud/read-operations/cursor.txt

@@ -242,20 +242,20 @@ You can use the following methods to retrieve documents as an array:
 Specify Cursor Behavior
 -----------------------
 
-To modify the cursor that an operation returns, pass options to
+To modify the cursor that an operation returns, chain option builder methods to
 the method that returns the ``Cursor`` instance. For example, you can
-specify cursor-related options in a ``FindOptions`` type that you pass to the
-``find()`` method.
+chain cursor-related option builder methods to the ``find()`` method.
 
-.. note:: Instantiating Options
+.. note:: Setting Options
 
-   The {+driver-short+} implements the Builder design pattern for the
-   creation of many different types, including ``FindOptions``. You can
-   use each type's ``builder()`` method to construct an options instance
-   by chaining option builder functions one at a time.
+   You can set ``FindOptions`` fields by chaining option builder methods directly
+   to the ``find()`` method call. If you're using an earlier version of the
+   driver, you must construct a ``FindOptions`` instance by chaining option
+   builder methods to the ``builder()`` method. Then, pass your ``FindOptions``
+   instance as a parameter to ``find()``.
 
-The following table describes cursor-related options that you can set in
-an options instance:
+The following table describes cursor-related options that you can set by
+calling their corresponding builder method:
 
 .. list-table::
    :widths: 30 70
@@ -298,8 +298,8 @@ an options instance:
        | Type: ``bool``
        | Default: ``false``
 
-The following code shows how to construct a ``FindOptions``
-instance and specify cursor-related settings:
+The following code shows how to specify cursor-related settings by chaining
+option builder methods to the ``find()`` method:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/crud/cursor.rs
    :start-after: start-options