DOCSP-18444 example section (#42)

kyuan-mongodb · web-flow · commit 2b99c4f42c36 · 2021-09-08T15:00:22.000-04:00
* updated all example sections
diff --git a/source/usage-examples/bulkWrite.txt b/source/usage-examples/bulkWrite.txt
@@ -7,14 +7,17 @@ Perform Bulk Operations
 You can perform bulk write operations on a collection by using the
 ``BulkWrite()`` method.
 
-The following example specifies a slice of ``WriteModels`` and an option
-to the ``BulkWrite()`` method, which performs the following in order:
-
-- Match a document where the ``title`` is "Record of a Shriveled Datum" and replace it with a new document
-- Match a document where the ``title`` is "Dodging Greys" and update that field to "Dodge The Greys"
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example performs the following in order on the ``haikus``
+collection:
+
+- Matches a document in which the ``title`` is "Record of a Shriveled Datum" and replace it with a new document
+- Matches a document in which the ``title`` is "Dodging Greys" and updates that value to "Dodge The Greys"
+
 .. literalinclude:: /includes/usage-examples/code-snippets/bulk.go
    :start-after: begin bulk
    :end-before: end bulk
diff --git a/source/usage-examples/command.txt b/source/usage-examples/command.txt
@@ -7,12 +7,14 @@ Run a Command
 You can run commands directly on your MongoDB server by using the
 ``RunCommand()`` method.
 
-The following example passes a document containing the ``"dbStats"``
-command to the ``RunCommand()`` method, which retrieves statistics
-about the ``sample_restaurants`` database:
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example retrieves statistics about the
+``sample_restaurants`` database: 
+
 .. literalinclude:: /includes/usage-examples/code-snippets/command.go
    :start-after: begin runCommand
    :end-before: end runCommand
diff --git a/source/usage-examples/count.txt b/source/usage-examples/count.txt
@@ -9,14 +9,17 @@ collection by using the ``EstimatedDocumentCount()`` method and an exact
 number of documents in a collection by using the ``CountDocuments()``
 method.
 
-The following example uses the ``EstimatedDocumentCount()`` method to
-count the number of documents in the ``movies`` collection. Then, the
-example uses the ``CountDocuments()`` method to count the number of
-documents in the ``movies`` collection where the ``countries`` field
-contains "China".
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example performs the following on the ``movies``
+collection:
+
+- Approximates the number of documents in the collection
+- Counts the number of documents in which the ``countries`` contains "China"
+
 .. literalinclude:: /includes/usage-examples/code-snippets/count.go
    :start-after: begin countDocuments
    :end-before: end countDocuments
diff --git a/source/usage-examples/deleteMany.txt b/source/usage-examples/deleteMany.txt
@@ -7,13 +7,15 @@ Delete Multiple Documents
 You can delete multiple documents in a collection by using the
 ``DeleteMany()`` method. 
 
-The following example specifies a query filter to the ``DeleteMany()``
-method, which matches documents in the ``movies`` collection where the
-``runtime`` field is greater than *800* and deletes all the matching
-documents. 
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example matches documents in the ``movies`` collection
+in which the ``runtime`` is greater than 800 minutes, deleting all 
+documents matched:
+
 .. literalinclude:: /includes/usage-examples/code-snippets/deleteMany.go
    :start-after: begin deleteMany
    :end-before: end deleteMany
diff --git a/source/usage-examples/deleteOne.txt b/source/usage-examples/deleteOne.txt
@@ -7,13 +7,15 @@ Delete a Document
 You can delete a document in a collection by using the ``DeleteOne()``
 method. 
 
-The following example specifies a query filter to the ``DeleteOne()``
-method, which matches documents in the ``movies`` collection where the
-``title`` field is "Twilight", and deletes the first document that
-matches. 
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example matches documents in the ``movies`` collection
+in which the ``title`` is "Twilight", deleting the first document
+matched:
+
 .. literalinclude:: /includes/usage-examples/code-snippets/deleteOne.go
    :start-after: begin deleteOne
    :end-before: end deleteOne
diff --git a/source/usage-examples/distinct.txt b/source/usage-examples/distinct.txt
@@ -7,13 +7,17 @@ Retrieve Distinct Values of a Field
 You can retrieve a list of distinct values for a field across a
 collection by using the ``Distinct()`` method.
 
-The following example specifies a query filter and a field name to the
-``Distinct()`` method, which matches documents in the ``movies``
-collection where the ``directors`` field contains "Natalie Portman" and
-returns distinct values of the ``title`` field from the matched documents.
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example performs the following on the ``movies``
+collection:
+
+- Matches documents in which the ``directors`` contains "Natalie Portman" 
+- Returns distinct values of the ``title`` from the matched documents
+
 .. literalinclude:: /includes/usage-examples/code-snippets/distinct.go
    :start-after: begin distinct
    :end-before: end distinct
diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt
@@ -7,12 +7,15 @@ Find Multiple Documents
 You can find multiple documents in a collection by using the ``Find()``
 method.
 
-The following example passes a query filter to the ``Find()`` method,
-which matches documents in the ``zips`` collection where the value of the
-``pop`` field is less than or equal to *500*:
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example matches documents in the ``zips`` collection
+in which the ``pop`` is less than or equal to 500 people,
+returning all documents matched:
+
 .. literalinclude:: /includes/usage-examples/code-snippets/find.go
    :start-after: begin find
    :end-before: end find
diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt
@@ -7,12 +7,15 @@ Find a Document
 You can retrieve a single document from a collection by using the
 ``FindOne()`` method.
 
-The following example passes a query filter to the ``FindOne()`` method,
-which matches documents in the ``movies`` collection where the value
-of the ``title`` field is *The Room*, returning the first document found.
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example matches documents in the ``movies`` collection
+in which the ``title`` is "The Room", returning the first document 
+matched:
+
 .. literalinclude:: /includes/usage-examples/code-snippets/findOne.go
    :start-after: begin findOne
    :end-before: end findOne
diff --git a/source/usage-examples/insertMany.txt b/source/usage-examples/insertMany.txt
@@ -7,17 +7,18 @@ Insert Multiple Documents
 You can insert multiple documents into a collection by using the ``InsertMany()``
 method.
 
-The following example creates a two new document containing a ``title`` and ``text``
-field and inserts it into the ``haikus`` collection of the ``insertDB`` database:
+Example
+-------
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+The following example inserts two documents in the ``haikus`` collection: 
 
 .. note:: Non-existent Database and Collections
 
     The driver automatically creates the necessary database and/or collection
     when you perform a write operation against them if they don't already exist.
 
-
-.. include:: /includes/usage-examples/run-example-tip.rst
-
 .. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go
    :start-after: begin insertMany
    :end-before: end insertMany
diff --git a/source/usage-examples/insertOne.txt b/source/usage-examples/insertOne.txt
@@ -7,17 +7,18 @@ Insert a Document
 You can insert a document into a collection by using the ``InsertOne()``
 method.
 
-The following example creates a new document containing a ``title`` and ``text``
-field and inserts it into the ``haikus`` collection of the ``insertDB`` database:
+Example
+-------
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+The following example inserts a document in the ``haikus`` collection:
 
 .. note:: Non-existent Database and Collections
 
     The driver automatically creates the necessary database and/or collection
     when you perform a write operation against them if they don't already exist.
 
-
-.. include:: /includes/usage-examples/run-example-tip.rst
-
 .. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go
    :start-after: begin insertOne
    :end-before: end insertOne
diff --git a/source/usage-examples/replaceOne.txt b/source/usage-examples/replaceOne.txt
@@ -7,14 +7,17 @@ Replace a Document
 You can replace a document in a collection by using the ``ReplaceOne()``
 method.
 
-The following example specifies a query filter and replacement document
-to the ``ReplaceOne()`` method, which matches a document in the
-``haikus`` collection where the ``title`` field is "Record of a
-Shriveled Datum" and replaces it with a document that contains a
-``title`` and ``text`` field about a haiku:
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example performs the following on the ``haikus``
+collection:
+
+- Matches a document in which the ``title`` is "Record of a Shriveled Datum"
+- Replaces the matched document with a new document
+
 .. literalinclude:: /includes/usage-examples/code-snippets/replace.go
    :start-after: begin replace
    :end-before: end replace
diff --git a/source/usage-examples/struct-tagging.txt b/source/usage-examples/struct-tagging.txt
@@ -7,10 +7,15 @@ Use Struct Tags
 You can specify the way that the Go Driver converts Go
 structs to :manual:`BSON </reference/bson-types/>` by using struct tags.
 
-The following code declares a ``BlogPost`` struct, where the ``WordCount`` field
-has a struct tag that sets a custom BSON field name of ``word_count``.
-By default, the driver marshals the other fields as the lowercase of the struct
-field name:
+Example
+-------
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+The following code declares a struct of type ``BlogPost``. This struct
+contains a struct tag that maps the ``WordCount`` field to the BSON
+field name ``word_count``. By default, the driver marshals the other
+fields as the lowercase of the struct field name:
 
 .. literalinclude:: /includes/usage-examples/code-snippets/struct-tag.go
    :start-after: begin struct
diff --git a/source/usage-examples/updateMany.txt b/source/usage-examples/updateMany.txt
@@ -7,14 +7,17 @@ Update Multiple Documents
 You can update multiple documents in a collection by using the ``UpdateMany()``
 method.
 
-The following example passes a query filter and an update parameter to the
-``UpdateMany()`` method, which matches documents in the
-``listingsAndReviews`` collection where the value of the ``address.market``
-field is "Sydney" and multiplies the ``price`` field in the matching
-documents by a factor of *1.15*:
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example performs the following on the
+``listingsAndReviews`` collection:
+
+- Matches documents in which the market field of the address subdocument, ``address.market`` is "Sydney"
+- Updates the ``price`` in the matched documents by 1.15 times
+
 .. literalinclude:: /includes/usage-examples/code-snippets/updateMany.go
    :start-after: begin updatemany
    :end-before: end updatemany
diff --git a/source/usage-examples/updateOne.txt b/source/usage-examples/updateOne.txt
@@ -7,13 +7,17 @@ Update a Document
 You can update a document in a collection by using the ``UpdateOne()``
 method. 
 
-The following example passes a query filter and an update parameter to the
-``UpdateOne()`` method, which matches a document in the ``restaurants`` collection
-by the value of its ``_id`` field and creates a new field in that document called
-``avg_rating`` with a value of *4.4*:
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example performs the following on the ``restaurants``
+collection:
+
+- Matches a document with a specific ``_id`` 
+- Creates a new field in the matched document called ``avg_rating`` with a value of 4.4
+
 .. literalinclude:: /includes/usage-examples/code-snippets/updateOne.go
    :start-after: begin updateone
    :end-before: end updateone
diff --git a/source/usage-examples/watch.txt b/source/usage-examples/watch.txt
@@ -7,11 +7,14 @@ Watch for Changes
 You can open a change stream on a ``MongoCollection``,
 ``MongoDatabase``, or ``MongoClient`` by using the ``Watch()`` method.
 
-The following example uses the ``Watch()`` method, to open a change
-stream on the ``haikus`` collection and prints inserted documents:
+Example
+-------
 
 .. include:: /includes/usage-examples/run-example-tip.rst
 
+The following example opens a change stream on the ``haikus`` collection
+and prints inserted documents:
+
 .. literalinclude:: /includes/usage-examples/code-snippets/watch.go
    :start-after: begin watch
    :end-before: end watch
