NR feedback

Author: rachel-mack

source/crud/read-operations/retrieve.txt

@@ -15,7 +15,7 @@ Retrieve Data
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Overview
@@ -63,7 +63,8 @@ specify a query, see our :doc:`Specify a Query
 </crud/query-document>` guide.
 
 To retrieve a single document, you can append the ``first()`` method to your
-``find()`` operation.
+``find()`` operation. You can use the ``sort()`` operation before selecting the first
+document to help choose the correct file.
 
 Example
 ~~~~~~~
@@ -96,12 +97,14 @@ criteria.
 Find Example: Full File
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-The following code is a complete, standalone file that performs a find
-operation to retrieve multiple douments, and a find operation with the first
-method to retrieve a single document. 
-
 .. include:: /includes/crud/example-intro.rst
 
+The following code is a complete, standalone file that performs the following
+actions:
+
+- Calls the ``find()`` method to retrieve multiple documents that have a ``runtime`` value less than 15, applying a projection and sort to the results 
+- Calls the ``find()`` and ``first()`` method to retrieve a document that has a ``title`` value of ``"The Room"``, applying a projection and sort before returning the first match 
+
 .. io-code-block::
 
    .. input:: /includes/crud/Find.java
@@ -114,7 +117,7 @@ method to retrieve a single document.
 
       Number of documents found with find(): 101
 
-      Document found with find().first(){"title": "The Room", "imdb": {"rating": 3.5, "votes": 25673, "id": 368226}}
+      Document found with find().first(): {"title": "The Room", "imdb": {"rating": 3.5, "votes": 25673, "id": 368226}}
 
 .. _retrieve-aggregate:
 
@@ -166,19 +169,22 @@ purchased color.
 For more information about how to construct an aggregation pipeline, see
 the {+mdb-server+} manual page on :manual:`Aggregation </aggregation>`.
 
+Additional Information
+----------------------
+
 API Documentation
------------------
+~~~~~~~~~~~~~~~~~
 
-For more information on the methods and classes used to retrieve documents
-on this page, see the following API Documentation:
+For more information about the methods and classes used to retrieve documents
+on this page, see the following API cocumentation:
 
 - `find() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#find()>`__
 - `first() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#first()>`__
 - `FindIterable <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html>`__
 - `aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__
 
 Server Manual Entries
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`Collections </core/databases-and-collections/#collections>`
 - :manual:`Query Documents </tutorial/query-documents>`

source/crud/write-operations/bulk.txt

@@ -360,16 +360,17 @@ see the following API documentation:
 - `ordered() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html#ordered(boolean)>`__
 
 
-BulkWrite Example: Full File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following code is a complete, standalone file that performs an ordered bulk
-write operation. 
+Bulk Write Example: Full File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: /includes/crud/example-intro.rst
 
-This example call to ``bulkWrite()`` includes examples of the ``InsertOneModel``,
-``UpdateOneModel``, ``DeleteOneModel``, and ``ReplaceOneModel``. 
+The following code is a complete, standalone file that performs the following
+actions:
+
+#. Creates a list of instances of the ``InsertOneModel``, ``UpdateOneModel``,
+   ``DeleteOneModel``, and ``ReplaceOneModel`` classes.
+#. Runs an ordered ``bulkWrite()`` operation on the list.
 
 .. io-code-block::
 
@@ -634,28 +635,31 @@ Even though the write operation inserting a document with a duplicate key result
 in an error, the other operations are executed because the write operation is
 unordered.
 
+Additional Information
+----------------------
+
 API Documentation
------------------
+~~~~~~~~~~~~~~~~~
 
 To learn more about the methods and classes used to perform bulk write
 operations in this section, see the following API documentation:
 
 MongoCollection
-~~~~~~~~~~~~~~~
+```````````````
 
 - `bulkWrite() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__
 - `BulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html>`__
 - `MongoBulkWriteException <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoBulkWriteException.html>`__
 
 MongoClient
-~~~~~~~~~~~
+````````````
 
 - `bulkWrite() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCluster.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__
 - `ClientBulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientBulkWriteOptions.html>`__
 - `ClientBulkWriteResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientBulkWriteResult.html>`__
 
 Server Manual Entries
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`MongoCollection.bulkWrite() </reference/method/db.collection.bulkWrite/>`
 - :manual:`MongoClient.bulkWrite() </reference/command/bulkWrite/>`

source/crud/write-operations/delete.txt

@@ -151,15 +151,10 @@ collection:
 Delete Example: Full File
 -------------------------
 
-The following code is a complete, standalone file that performs a delete one
-operation and a delete many operation. 
-
 .. include:: /includes/crud/example-intro.rst
 
-The query uses the ``eq()`` and ``lt()`` filters to query documents. For more
-information about filters, see the `Filters Class
-<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Filters.html>`__
-API documentation.
+The following code is a complete, standalone file that performs a delete one
+operation and a delete many operation. 
 
 .. io-code-block::
 
@@ -174,10 +169,19 @@ API documentation.
       DeleteOne document count: 1
       DeleteMany document count: 4
 
+
+The query in this examples uses the ``eq()`` and ``lt()`` filters to query documents. For more
+information about filters, see the `Filters Class
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Filters.html>`__
+API documentation.
+
+Additional Information
+----------------------
+
 API Documentation
------------------
+~~~~~~~~~~~~~~~~~
 
-For more information on the methods and classes used to delete documents, see the following API Documentation: 
+For more information about the methods and classes used to delete documents, see the following API cocumentation: 
 
 - `deleteOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteOne(org.bson.conversions.Bson)>`__  
 - `deleteMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteMany(org.bson.conversions.Bson)>`__ 
@@ -187,7 +191,7 @@ For more information on the methods and classes used to delete documents, see th
 - `DeleteResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/DeleteResult.html>`__ 
 
 Server Manual Entries
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`db.collection.deleteOne() </reference/method/db.collection.deleteOne/>`
 - :manual:`db.collection.deleteMany() </reference/method/db.collection.deleteMany/>`

source/crud/write-operations/insert.txt

@@ -30,11 +30,12 @@ The following sections focus on ``insertOne()`` and
 method, see our
 :doc:`guide on Bulk Operations </crud/write-operations/bulk/>`. 
 
-.. note:: The ``id_`` field in Insert Operations
+.. note:: The ``id_`` Field in Insert Operations
 
    When inserting a document, MongoDB enforces one constraint on your
-   documents by default: each document *must* contain a unique ``_id``
-   field. Duplicate ``_id`` values violate unique index constraints, resulting in a ``WriteError``.
+   documents by default: each document *must* contain a unique ``_id`` value.
+   Duplicate ``_id`` values violate unique index constraints, resulting in a
+   ``WriteError``. 
 
    There are two ways to manage this field:
 
@@ -44,7 +45,7 @@ method, see our
    Unless you have provided strong guarantees for uniqueness, we recommend
    you let the driver automatically generate ``_id`` values.  
 
-   For more information on unique indexes, see the manual entry on 
+   For more information about unique indexes, see the manual entry on 
    :manual:`Unique Indexes </core/index-unique/>`.
 
 Insert a Single Document
@@ -158,11 +159,11 @@ The output of the preceding code resembles the following:
 Insert Example: Full File
 -------------------------
 
+.. include:: /includes/crud/example-intro.rst
+
 The following code is a complete, standalone file that performs an insert one
 operation and an insert many operation. 
 
-.. include:: /includes/crud/example-intro.rst
-
 .. io-code-block::
 
    .. input:: /includes/crud/Insert.java
@@ -176,18 +177,21 @@ operation and an insert many operation.
       InsertOne document id: BsonObjectId{value=...}
       InsertMany document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}
 
+Additional Information
+----------------------
+
 API Documentation
------------------
+~~~~~~~~~~~~~~~~~
 
-For more information on the methods and classes used to insert documents, see the following API Documentation: 
+For more information about the methods and classes used to insert documents, see the following API cocumentation: 
 
 - `insertOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertOne(TDocument)>`__
 - `InsertOneResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertOneResult.html>`__
 - `insertMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertMany(java.util.List)>`__
 - `InsertManyResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertManyResult.html>`__ 
 
 Server Manual Entries
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`db.collection.insertOne() </reference/method/db.collection.insertOne/>`
 - :manual:`db.collection.insertMany() </reference/method/db.collection.insertMany/>`

source/crud/write-operations/modify.txt

@@ -283,10 +283,10 @@ documents match.
 ReplaceOne Example: Full File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following code is a complete, standalone file that performs a replace one operation. 
-
 .. include:: /includes/crud/example-intro.rst
 
+The following code is a complete, standalone file that performs a replace one operation. 
+
 .. io-code-block::
 
    .. input:: /includes/crud/ReplaceOne.java
@@ -302,10 +302,13 @@ The following code is a complete, standalone file that performs a replace one op
 
       UpdateMany modified document count: 242
 
+Additional Information
+----------------------
+
 API Documentation
------------------
+~~~~~~~~~~~~~~~~~
 
-For more information on the methods and classes used to modify documents, see the following API Documentation:
+For more information about the methods and classes used to modify documents, see the following API cocumentation:
 
 - `updateOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,java.util.List,com.mongodb.client.model.UpdateOptions)>`__
 - `updateMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,java.util.List,com.mongodb.client.model.UpdateOptions)>`__
@@ -314,8 +317,8 @@ For more information on the methods and classes used to modify documents, see th
 - `ReplaceOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html?is-external=true>`__
 - `UpdateResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/UpdateResult.html>`__
 
-For more information on the methods used in the examples on this
-page, see the following API Documentation:
+For more information about the methods used in the examples on this
+page, see the following API cocumentation:
 
 - `eq() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Filters.html#eq(java.lang.String,TItem)>`__
 - `combine() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html#combine(org.bson.conversions.Bson...)>`__
@@ -324,7 +327,7 @@ page, see the following API Documentation:
 - `currentTimestamp() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html#currentTimestamp(java.lang.String)>`__
 
 Server Manual Entries
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`db.collection.updateOne() </reference/method/db.collection.updateOne/>`
 - :manual:`db.collection.updateMany() </reference/method/db.collection.updateMany/>`

source/includes/crud/Delete.java

@@ -32,7 +32,7 @@ public static void main(String[] args) {
             try {
                 // Deletes the first document that has a "title" value of "The Garbage Pail Kids Movie"
                 DeleteResult result = collection.deleteOne(deleteOneQuery);
-                System.out.println("DeleteOne document count: " + result.getDeletedCount());
+                System.out.println("deleteOne() document count: " + result.getDeletedCount());
 
             // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {
@@ -46,7 +46,7 @@ public static void main(String[] args) {
                 DeleteResult result = collection.deleteMany(deleteManyQuery);
 
                 // Prints the number of deleted documents
-                System.out.println("DeleteMany document count: " + result.getDeletedCount());
+                System.out.println("deleteMany() document count: " + result.getDeletedCount());
 
             // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {

source/includes/crud/Find.java

@@ -48,7 +48,7 @@ public static void main( String[] args ) {
             if (doc == null) {
                 System.out.println("No results found.");
             } else {
-                System.out.println("Document found with find().first()" + doc.toJson());
+                System.out.println("Document found with find().first(): " + doc.toJson());
             }
         }
     }

source/includes/crud/Insert.java

@@ -34,7 +34,7 @@ public static void main(String[] args) {
                         .append("genres", Arrays.asList("Documentary", "Comedy")));
 
                 // Prints the ID of the inserted document
-                System.out.println("InsertOne document id: " + result.getInsertedId());
+                System.out.println("insertOne() document id: " + result.getInsertedId());
 
             // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {
@@ -51,7 +51,7 @@ public static void main(String[] args) {
                 InsertManyResult result = collection.insertMany(movieList);
 
                 // Prints the IDs of the inserted documents
-                System.out.println("InsertMany document ids: " + result.getInsertedIds());
+                System.out.println("insertMany() document ids: " + result.getInsertedIds());
 
             // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {

source/includes/crud/example-intro.rst

@@ -1,8 +1,10 @@
-This example connects to an instance of MongoDB using a connection URI. To learn
-more about connecting to your MongoDB instance, see the :ref:`connection guide
-<connect-to-mongodb>`. It also uses the ``movies`` collection in the
-``sample_mflix`` database included in the :atlas:`sample datasets
-</sample-data?jmp=docs_driver_java>` provided by Atlas. You can load them into
-your database on the free tier of MongoDB Atlas by following the :atlas:`Get
-Started with Atlas Guide
-</getting-started/#atlas-getting-started?jmp=docs_driver_java>`.
+.. note:: Example Setup
+
+    This example connects to an instance of MongoDB by using a connection URI. To learn
+    more about connecting to your MongoDB instance, see the :ref:`connection guide
+    <connect-to-mongodb>`. This example also uses the ``movies`` collection in the
+    ``sample_mflix`` database included in the :atlas:`Atlas sample datasets
+    </sample-data?jmp=docs_driver_java>`. You can load them into
+    your database on the free tier of MongoDB Atlas by following the :atlas:`Get
+    Started with Atlas Guide
+    </getting-started/#atlas-getting-started?jmp=docs_driver_java>`.