DOCSP-44967: Data modeling in update examples (#143)

(cherry picked from commit 734ed06)

Author: norareidy

source/includes/usage-examples/code-snippets/replace-async.rs

@@ -14,18 +14,26 @@ async fn main() -> mongodb::error::Result<()> {
     let uri = "<connection string>";
 
     let client = Client::with_uri_str(uri).await?;
-    let my_coll: Collection<Restaurant> = client
+
+    // Replace <T> with the <Document> or <Restaurant> type parameter
+    let my_coll: Collection<T> = client
         .database("sample_restaurants")
         .collection("restaurants");
 
     let filter = doc! { "name": "Landmark Coffee Shop" };
-    let replacement = Restaurant {
+    let replace_doc = doc! { 
+        "borough": "Brooklyn",
+        "cuisine": "Café/Coffee/Tea",
+        "name": "Harvest Moon Café",
+    };
+    let replace_struct = Restaurant {
         borough: "Brooklyn".to_string(),
         cuisine: "Café/Coffee/Tea".to_string(),
         name: "Harvest Moon Café".to_string(),
     };
 
-    let res = my_coll.replace_one(filter, replacement).await?;
+    // Replace <struct or doc> with the replace_struct or replace_doc variable
+    let res = my_coll.replace_one(filter, <struct or doc>).await?;
     println!("Replaced documents: {}", res.modified_count);
 
     Ok(())

source/includes/usage-examples/code-snippets/replace-sync.rs

@@ -13,18 +13,26 @@ fn main() -> mongodb::error::Result<()> {
     let uri = "<connection string>";
 
     let client = Client::with_uri_str(uri)?;
-    let my_coll: Collection<Restaurant> = client
+
+    // Replace <T> with the <Document> or <Restaurant> type parameter
+    let my_coll: Collection<T> = client
         .database("sample_restaurants")
         .collection("restaurants");
 
     let filter = doc! { "name": "Landmark Coffee Shop" };
-    let replacement = Restaurant {
+    let replace_doc = doc! { 
+        "borough": "Brooklyn",
+        "cuisine": "Café/Coffee/Tea",
+        "name": "Harvest Moon Café",
+    };
+    let replace_struct = Restaurant {
         borough: "Brooklyn".to_string(),
         cuisine: "Café/Coffee/Tea".to_string(),
         name: "Harvest Moon Café".to_string(),
     };
 
-    let res = my_coll.replace_one(filter, replacement).run()?;
+    // Replace <struct or doc> with the replace_struct or replace_doc variable 
+    let res = my_coll.replace_one(filter, <struct or doc>).run()?;
     println!("Replaced documents: {}", res.modified_count);
 
     Ok(())

source/includes/usage-examples/code-snippets/update-many-async.rs

@@ -1,13 +1,29 @@
 use std::env;
 use mongodb::{ bson::doc, Client, Collection };
 use bson::Document;
+use serde::{ Deserialize, Serialize };
+
+#[derive(Debug, Serialize, Deserialize)]
+struct Address {
+    street: String,
+    city: String,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    borough: String,
+    address: Address,
+}
 
 #[tokio::main]
 async fn main() -> mongodb::error::Result<()> {
     let uri = "<connection string>";
 
     let client = Client::with_uri_str(uri).await?;
-    let my_coll: Collection<Document> = client
+
+    // Replace <T> with the <Document> or <Restaurant> type parameter
+    let my_coll: Collection<T> = client
         .database("sample_restaurants")
         .collection("restaurants");
 

source/includes/usage-examples/code-snippets/update-many-sync.rs

@@ -3,12 +3,28 @@ use mongodb::{
     bson::{ Document, doc },
     sync::{ Client, Collection } 
 };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Debug, Serialize, Deserialize)]
+struct Address {
+    street: String,
+    city: String,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    borough: String,
+    address: Address,
+}
 
 fn main() -> mongodb::error::Result<()> {
     let uri = "<connection string>";
 
     let client = Client::with_uri_str(uri)?;
-    let my_coll: Collection<Document> = client
+
+    // Replace <T> with the <Document> or <Restaurant> type parameter
+    let my_coll: Collection<T> = client
         .database("sample_restaurants")
         .collection("restaurants");
 

source/includes/usage-examples/code-snippets/update-one-async.rs

@@ -4,13 +4,22 @@ use mongodb::{
     Client,
     Collection
 };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    price: String,
+}
 
 #[tokio::main]
 async fn main() -> mongodb::error::Result<()> {
     let uri = "<connection string>";
 
     let client = Client::with_uri_str(uri).await?;
-    let my_coll: Collection<Document> = client
+
+    // Replace <T> with the <Document> or <Restaurant> type parameter
+    let my_coll: Collection<T> = client
         .database("sample_restaurants")
         .collection("restaurants");
 

source/includes/usage-examples/code-snippets/update-one-sync.rs

@@ -3,12 +3,21 @@ use mongodb::{
     bson::{ Document, doc },
     sync::{ Client, Collection }
 };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    price: String,
+}
 
 fn main() -> mongodb::error::Result<()> {
     let uri = "<connection string>";
 
     let client = Client::with_uri_str(uri)?;
-    let my_coll: Collection<Document> = client
+
+    // Replace <T> with the <Document> or <Restaurant> type parameter
+    let my_coll: Collection<T> = client
         .database("sample_restaurants")
         .collection("restaurants");
 

source/usage-examples/find.txt

@@ -42,7 +42,7 @@ This example retrieves documents that match a query filter from the ``restaurant
 collection in the ``sample_restaurants`` database. The ``find()`` method returns
 all documents in which the value of the ``cuisine`` field is ``"French"``.
 
-You can model each retrieved document as a BSON data type or a custom data type. To specify
+You can model each retrieved document as a ``Document`` type or a custom data type. To specify
 which data type represents the collection's data, replace the ``<T>`` type parameter on the
 highlighted line with one of the following values:
 

source/usage-examples/findOne.txt

@@ -38,7 +38,7 @@ This example retrieves a document that matches a query filter from the ``restaur
 collection in the ``sample_restaurants`` database. The ``find_one()`` method returns the
 first document in which the value of the ``name`` field is ``"Tompkins Square Bagels"``.
 
-You can model the retrieved document as a BSON data type or a custom data type. To specify
+You can model the retrieved document as a ``Document`` type or a custom data type. To specify
 which data type represents the collection's data, replace the ``<T>`` type parameter on the
 highlighted line with one of the following values:
 

source/usage-examples/replace.txt

@@ -26,13 +26,22 @@ Example
 -------
 
 This example replaces a document in the ``restaurants`` collection of
-the ``sample_restaurants`` database. The example uses a ``Restaurant``
-struct that has ``name``, ``borough``, and ``cuisine`` fields to model
-documents in the collection.
+the ``sample_restaurants`` database. The ``replace_one()`` method replaces
+the first document in which the value of the ``name`` field is
+``"Landmark Coffee Shop"`` with a new document.
 
-The following code replaces a document in which the value of the
-``name`` field is ``"Landmark Coffee Shop"`` with a new document. MongoDB
-replaces the first document that matches the query filter.
+You can access the documents in the ``restaurants`` collection as instances
+of the ``Document`` type or a custom data type. To specify which data type represents
+the collection's data, perform the following actions on the highlighted lines:
+
+- To access collection documents as BSON documents, replace the ``<T>`` type
+  parameter with ``<Document>`` and the ``<struct or doc>`` placeholder with
+  ``replace_doc``.
+
+- To access collection documents as instances of the ``Restaurant`` struct,
+  replace the ``<T>`` type parameter with ``<Restaurant>`` and the ``<struct or doc>``
+  placeholder with ``replace_struct``. The ``Restaurant`` struct is defined at
+  the top of the code file.
 
 Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to
 see the corresponding code for each runtime:
@@ -47,6 +56,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/replace-async.rs
             :language: rust
+            :emphasize-lines: 19, 36
             :dedent:
 
          .. output::
@@ -63,6 +73,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/replace-sync.rs
             :language: rust
+            :emphasize-lines: 18, 35
             :dedent:
 
          .. output::

source/usage-examples/updateMany.txt

@@ -26,11 +26,18 @@ Example
 -------
 
 This example updates a document in the ``restaurants`` collection of
-the ``sample_restaurants`` database.
+the ``sample_restaurants`` database. The ``update_many()`` method adds
+the ``near_me`` field to documents in which the value of the ``address.street``
+field is ``"Sullivan Street"`` and the ``borough`` field is ``"Manhattan"``.
 
-The following code adds the ``near_me`` field to documents in which the
-value of the ``address.street`` field is ``"Sullivan Street"`` and the
-``borough`` field is ``"Manhattan"``.
+You can access the documents in the ``restaurants`` collection as instances
+of the ``Document`` type or a custom data type. To specify which data type represents
+the collection's data, replace the ``<T>`` type parameter on the highlighted
+line with one of the following values:
+
+- ``<Document>``: Accesses collection documents as BSON documents.
+- ``<Restaurant>``: Accesses collection documents as instances of the ``Restaurant``
+  struct, defined at the top of the code
 
 Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to
 see the corresponding code for each runtime:
@@ -45,6 +52,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/update-many-async.rs
             :language: rust
+            :emphasize-lines: 25
             :dedent:
 
          .. output::
@@ -62,6 +70,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/update-many-sync.rs
             :language: rust
+            :emphasize-lines: 26
             :dedent:
 
          .. output::

source/usage-examples/updateOne.txt

@@ -4,6 +4,19 @@
 Update a Document
 =================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: modify, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 You can update a document in a collection by calling the `update_one()
 <{+api+}/struct.Collection.html#method.update_one>`__ method on a
 ``Collection`` instance.
@@ -26,11 +39,18 @@ Example
 -------
 
 This example updates a document in the ``restaurants`` collection of
-the ``sample_restaurants`` database.
+the ``sample_restaurants`` database. The ``update_one()`` method adds
+the ``price`` field to the first document in which the value of the ``name``
+field is ``"Spice Market"``.
+
+You can access the documents in the ``restaurants`` collection as instances
+of the ``Document`` type or a custom data type. To specify which data type represents
+the collection's data, replace the ``<T>`` type parameter on the highlighted
+line with one of the following values:
 
-The following code adds the ``price`` field to a document in which the
-value of the ``name`` field is ``"Spice Market"``. MongoDB
-updates the first document that matches the query filter.
+- ``<Document>``: Accesses collection documents as BSON documents
+- ``<Restaurant>``: Accesses collection documents as instances of the ``Restaurant``
+  struct, defined at the top of the code
 
 Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to
 see the corresponding code for each runtime:
@@ -45,6 +65,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/update-one-async.rs
             :language: rust
+            :emphasize-lines: 21
             :dedent:
 
          .. output::
@@ -61,6 +82,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/update-one-sync.rs
             :language: rust
+            :emphasize-lines: 19
             :dedent:
 
          .. output::