DOCSP-44969: Modify insert usage examples (#154)

Author: norareidy

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

@@ -1,5 +1,5 @@
 use mongodb::{ 
-    bson::doc,
+    bson::{doc, Document},
     Client,
     Collection 
 };
@@ -16,11 +16,22 @@ 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 docs = vec! [
+    let insert_docs = vec! [
+        doc! { 
+            "name": "While in Kathmandu",
+            "cuisine": "Nepalese",
+        },
+        doc! { 
+            "name": "Cafe Himalaya",
+            "cuisine": "Nepalese",
+        }
+    ];
+    let insert_structs = vec! [
         Restaurant {
             name: "While in Kathmandu".to_string(),
             cuisine: "Nepalese".to_string(),
@@ -31,7 +42,8 @@ async fn main() -> mongodb::error::Result<()> {
         }
     ];
 
-    let insert_many_result = my_coll.insert_many(docs).await?;
+    // Replace <structs or docs> with the insert_structs or insert_docs variable
+    let insert_many_result = my_coll.insert_many(<structs or docs>).await?;
     println!("Inserted documents with _ids:");
     for (_key, value) in &insert_many_result.inserted_ids {
         println!("{}", value);

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

@@ -1,5 +1,5 @@
 use mongodb::{
-    bson::doc,
+    bson::{doc, Document},
     sync::{Client, Collection}
 };
 use serde::{ Deserialize, Serialize };
@@ -14,11 +14,22 @@ 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 docs = vec! [
+    let insert_docs = vec! [
+        doc! { 
+            "name": "While in Kathmandu",
+            "cuisine": "Nepalese",
+        },
+        doc! { 
+            "name": "Cafe Himalaya",
+            "cuisine": "Nepalese",
+        }
+    ];
+    let insert_structs = vec! [
         Restaurant {
             name: "While in Kathmandu".to_string(),
             cuisine: "Nepalese".to_string(),
@@ -29,7 +40,8 @@ fn main() -> mongodb::error::Result<()> {
         }
     ];
 
-    let insert_many_result = my_coll.insert_many(docs).run()?;
+    // Replace <structs or docs> with the insert_structs or insert_docs variable
+    let insert_many_result = my_coll.insert_many(<structs or docs>).run()?;
     println!("Inserted documents with _ids:");
     for (_key, value) in &insert_many_result.inserted_ids {
         println!("{}", value);

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

@@ -1,5 +1,9 @@
 use std::env;
-use mongodb::{ bson::doc, Client, Collection };
+use mongodb::{ 
+    bson::{doc, Document},
+    Client,
+    Collection 
+};
 use serde::{ Deserialize, Serialize };
 
 #[derive(Serialize, Deserialize, Debug)]
@@ -14,17 +18,25 @@ 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 doc = Restaurant {
+    let insert_doc = doc! { 
+        "name": "Sea Stone Tavern",
+        "cuisine": "Greek",
+        "borough": "Queens",
+    };
+    let insert_struct = Restaurant {
         name: "Sea Stone Tavern".to_string(),
         cuisine: "Greek".to_string(),
         borough: "Queens".to_string(),
     };
 
-    let res = my_coll.insert_one(doc).await?;
+    // Replace <struct or doc> with the insert_struct or insert_doc variable
+    let res = my_coll.insert_one(<struct or doc>).await?;
     println!("Inserted a document with _id: {}", res.inserted_id);
 
     Ok(())

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

@@ -1,5 +1,8 @@
 use std::env;
-use mongodb::{ bson::doc, sync::{ Client, Collection } };
+use mongodb::{
+    bson::{doc, Document},
+    sync::{ Client, Collection }
+};
 use serde::{ Deserialize, Serialize };
 
 #[derive(Serialize, Deserialize, Debug)]
@@ -13,17 +16,25 @@ 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 doc = Restaurant {
+    let insert_doc = doc! { 
+        "name": "Sea Stone Tavern",
+        "cuisine": "Greek",
+        "borough": "Queens",
+    };
+    let insert_struct = Restaurant {
         name: "Sea Stone Tavern".to_string(),
         cuisine: "Greek".to_string(),
         borough: "Queens".to_string(),
     };
 
-    let res = my_coll.insert_one(doc).run()?;
+    // Replace <struct or doc> with the insert_struct or insert_doc variable
+    let res = my_coll.insert_one(<struct or doc>).run()?;
     println!("Inserted a document with _id: {}", res.inserted_id);
 
     Ok(())

source/usage-examples/insertMany.txt

@@ -30,13 +30,23 @@ To learn more about inserting documents into a collection, see the
 Example
 -------
 
-This example inserts documents into the ``restaurants`` collection of the
-``sample_restaurants`` database. The example uses a ``Restaurant`` struct containing
-``name`` and ``cuisine`` fields to model the documents being inserted into the
-collection.
+This example inserts multiple documents into the ``restaurants`` collection of the
+``sample_restaurants`` database. The example inserts documents that have
+``name`` and ``cuisine`` field values by passing a vector of documents
+to the ``insert_many()`` method.
 
-This example passes a vector of documents as a parameter to the ``insert_many()``
-method.
+You can insert these documents 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 and insert collection documents as BSON documents, replace the ``<T>`` type
+  parameter with ``<Document>`` and the ``<struct or doc>`` placeholder with
+  ``insert_docs``.
+
+- To access and insert collection documents as instances of the ``Restaurant`` struct,
+  replace the ``<T>`` type parameter with ``<Restaurant>`` and the ``<struct or doc>``
+  placeholder with ``insert_structs``. 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:
@@ -51,6 +61,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/insert-many-async.rs
             :language: rust
+            :emphasize-lines: 20, 46
             :dedent:
 
          .. output::
@@ -69,6 +80,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/insert-many-sync.rs
             :language: rust
+            :emphasize-lines: 18, 44
             :dedent:
 
          .. output::

source/usage-examples/insertOne.txt

@@ -27,12 +27,22 @@ Example
 -------
 
 This example inserts a document into 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 ``insert_one()`` method 
+inserts a document that has ``name``, ``borough``, and ``cuisine`` field
+values.
 
-The following code creates a ``Restaurant`` instance and inserts it into
-the collection.
+You can insert this document as an instance 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 and insert collection documents as BSON documents, replace the ``<T>`` type
+  parameter with ``<Document>`` and the ``<struct or doc>`` placeholder with
+  ``insert_doc``.
+
+- To access and insert collection documents as instances of the ``Restaurant`` struct,
+  replace the ``<T>`` type parameter with ``<Restaurant>`` and the ``<struct or doc>``
+  placeholder with ``insert_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 +57,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/insert-one-async.rs
             :language: rust
+            :emphasize-lines: 23, 39
             :dedent:
 
          .. output::
@@ -63,6 +74,7 @@ see the corresponding code for each runtime:
 
          .. input:: /includes/usage-examples/code-snippets/insert-one-sync.rs
             :language: rust
+            :emphasize-lines: 21, 37
             :dedent:
 
          .. output::