DOCSP-33345: Java comments pt. 4 (#472)

* DOCSP-33345: Java code comments pt. 4

* bulkwrite CC feedback

* applying CC feedback

* small edit

* half of feedback

* rest of feedback

* single line comment

* duplicate comments sheet suggestions

* small edit

* final feedback

(cherry picked from commit 4b9070c)
(cherry picked from commit fd983e9)

Author: norareidy

source/includes/fundamentals/code-snippets/AggTour.java

@@ -14,6 +14,7 @@
 import org.bson.Document;
 
 import java.util.Arrays;
+import java.util.List;
 
 // end imports
 
@@ -30,6 +31,8 @@ public static void main(String[] args) {
         // end connection
 
         collection.drop();
+        
+        // Inserts sample documents describing restaurants
         // begin insert
         collection.insertMany(Arrays.asList(
             new Document("name", "Sun Bakery Trattoria").append("contact", new Document().append("phone", "386-555-0189").append("email", "[email protected]").append("location", Arrays.asList(-74.0056649, 40.7452371))).append("stars", 4).append("categories", Arrays.asList("Pizza", "Pasta", "Italian", "Coffee", "Sandwiches")),
@@ -45,32 +48,37 @@ public static void main(String[] args) {
         ));
         // end insert
 
+        // Creates an aggregation pipeline that matches documents, groups them by the "stars" field, and tallies them by distinct values
         // begin aggregation one
         collection.aggregate(
             Arrays.asList(
                 Aggregates.match(Filters.eq("categories", "Bakery")),
                 Aggregates.group("$stars", Accumulators.sum("count", 1))
             )
+        // Prints the result of the aggregation operation as JSON
         ).forEach(doc -> System.out.println(doc.toJson()));
         // end aggregation one
+
         // begin aggregation three
         Document explanation = collection.aggregate(
             Arrays.asList(
-                    Aggregates.match(Filters.eq("categories", "bakery")),
+                    Aggregates.match(Filters.eq("categories", "Bakery")),
                     Aggregates.group("$stars", Accumulators.sum("count", 1))
             )
         ).explain(ExplainVerbosity.EXECUTION_STATS);
 
         List<Document> stages = explanation.get("stages", List.class);
         List<String> keys = Arrays.asList("queryPlanner", "winningPlan");
 
+        // Prints the JSON representation of the winning execution plans
         for (Document stage : stages) {
             Document cursorStage = stage.get("$cursor", Document.class);
             if (cursorStage != null) {
                 System.out.println(cursorStage.getEmbedded(keys, Document.class).toJson());
             }
         }
         // end aggregation three
+        // Prints the restaurant name and the first value in the "categories" array as a field named "firstCategory"
         // begin aggregation two
         collection.aggregate(
             Arrays.asList(

source/includes/fundamentals/code-snippets/BulkWrite.java

@@ -73,68 +73,84 @@ private void insertExceptionExample() {
         // begin insertExceptionExample
         try {
             List<WriteModel<Document>> bulkOperations = new ArrayList<>();
-            
+
+            // Creates instructions to insert documents
             InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
             InsertOneModel<Document> doc3 = new InsertOneModel<>(new Document("_id", 3));
 
             bulkOperations.add(doc1);
             bulkOperations.add(doc3);
 
+            // Runs a bulk write operation for the specified insert WriteModels
             collection.bulkWrite(bulkOperations); 
 
+        // Prints a message if any exceptions occur during the bulk write operation
         } catch (MongoBulkWriteException e){
-            System.out.println("A MongoBulkWriteException occured with the following message: " + e.getMessage());
+            System.out.println("A MongoBulkWriteException occurred with the following message: " + e.getMessage());
         }
         //end insertExceptionExample
     }
 
     private void bulkWriteNotOrderedExample() {
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
-
+        // Creates instructions to insert a document
         InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
                                                                 .append("name", "Zaynab Omar")
                                                                 .append("age", 37));
+
+        // Creates instructions to replace the first document that matches the query
         ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1), 
                                                 new Document("name", "Sandy Kane")
-                                                    .append("location", "Helena, MT"));                            
+                                                    .append("location", "Helena, MT")); 
+        
+        // Creates instructions to update the first document that matches the query
         UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"), 
                                                 Updates.set("name", "Zaynab Hassan"));
+        
+        // Creates instructions to delete all documents that match the query
         DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));
 
-        bulkOperations.add(doc1);
-        bulkOperations.add(doc2);
-        bulkOperations.add(doc3);
-        bulkOperations.add(doc4);
-        
+        bulkOperations.add(insertDoc);
+        bulkOperations.add(replaceDoc);
+        bulkOperations.add(updateDoc);
+        bulkOperations.add(deleteDoc);
+
         // begin bulkWriteNotOrderedExample
         BulkWriteOptions options = new BulkWriteOptions().ordered(false);
 
+        // Runs a bulk write operation for the specified insert, replace, update, and delete WriteModels in any order
         collection.bulkWrite(bulkOperations, options); 
         //end bulkWriteNotOrderedExample
     }
 
     private void bulkWriteExample() {
         // begin bulkWriteExample
-
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
-
+        // Creates instructions to insert a document
         InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
-                                                                    .append("name", "Zaynab Omar")
-                                                                    .append("age", 37));
+                                                                .append("name", "Zaynab Omar")
+                                                                .append("age", 37));
+
+        // Creates instructions to replace the first document matched by the query                                       
         ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1), 
-                                            new Document("name", "Sandy Kane")
-                                                .append("location", "Helena, MT"));                            
-        UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"),
+                                                new Document("name", "Sandy Kane")
+                                                    .append("location", "Helena, MT")); 
+        
+        // Creates instructions to update the first document matched by the query                                                                 
+        UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"), 
                                                 Updates.set("name", "Zaynab Hassan"));
+        
+        // Creates instructions to delete all documents matched by the query                                
         DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));
 
         bulkOperations.add(doc1);
         bulkOperations.add(doc2);
         bulkOperations.add(doc3);
         bulkOperations.add(doc4);
 
+        // Runs a bulk write operation for the specified the insert, replace, update, and delete WriteModels in order
         collection.bulkWrite(bulkOperations);               
         //end bulkWriteExample
     }
@@ -143,14 +159,19 @@ private void insertDocumentsExample(){
         collection.drop();
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Creates instructions to insert multiple documents
         // begin insertDocumentsExample
-        InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 3));
-        InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 4));
+        InsertOneModel<Document> juneDoc = new InsertOneModel<>(new Document("name", "June Carrie")
+                                                                    .append("age", 17));
+                                                          
+        InsertOneModel<Document> kevinDoc = new InsertOneModel<>(new Document("name", "Kevin Moss")
+                                                                    .append("age", 22));
         //end insertDocumentsExample
 
         bulkOperations.add(doc1);
         bulkOperations.add(doc2);
 
+        // Runs a bulk write operation for the specified insert WriteModels
         collection.bulkWrite(bulkOperations);
     }
 
@@ -161,6 +182,7 @@ private void replaceDocumentsExample(){
         InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
         InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));
 
+        // Creates instructions to replace the first document matched by the query
         // begin replaceDocumentsExample
         ReplaceOneModel<Document> doc3 = new ReplaceOneModel<>(
                                             Filters.eq("_id", 1), 
@@ -172,6 +194,7 @@ private void replaceDocumentsExample(){
         bulkOperations.add(doc2);
         bulkOperations.add(doc3);
 
+        // Runs a bulk write operation for the specified replace WriteModel
         collection.bulkWrite(bulkOperations);
     }
 
@@ -182,6 +205,7 @@ private void updateDocumentsExample(){
         InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
         InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));
 
+        // Creates instructions to update the first document matched by the query
         // begin updateDocumentsExample
         UpdateOneModel<Document> doc3 = new UpdateOneModel<>(
                                             Filters.eq("_id", 2), 
@@ -192,6 +216,7 @@ private void updateDocumentsExample(){
         bulkOperations.add(doc2);
         bulkOperations.add(doc3);
 
+        // Runs a bulk write operation for the specified update WriteModel
         collection.bulkWrite(bulkOperations);
     }
 
@@ -202,6 +227,7 @@ private void deleteDocumentsExample(){
         InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
         InsertOneModel<Document> doc2 = new InsertOneModel<>(new Document("_id", 2));
 
+        // Creates instructions to delete the first document matched by the query
         // begin deleteDocumentsExample
         DeleteOneModel<Document> doc3 = new DeleteOneModel<>(Filters.eq("_id", 1));
         //end deleteDocumentsExample
@@ -210,6 +236,7 @@ private void deleteDocumentsExample(){
         bulkOperations.add(doc2);
         bulkOperations.add(doc3);
 
+        // Runs a bulk write operation for the specified delete WriteModel
         collection.bulkWrite(bulkOperations);
     }
 
@@ -227,15 +254,18 @@ private void setUpCollection(){
         InsertOneModel<Document> karen = new InsertOneModel<>(new Document("_id", 1)
                                                                 .append("name", "Karen Sandoval")
                                                                 .append("age", 31));
+                                                   
         InsertOneModel<Document> william = new InsertOneModel<>(new Document("_id", 2)
                                                                     .append("name", "William Chin")
                                                                     .append("age", 54));
+                                                        
         InsertOneModel<Document> shayla = new InsertOneModel<>(new Document("_id", 8)
                                                                     .append("name", "Shayla Ray")
                                                                     .append("age", 20));
-        
-        bulkOperations.add(doc1);
-        bulkOperations.add(doc2);
+
+        bulkOperations.add(karen);
+        bulkOperations.add(william);
+        bulkOperations.add(shayla);
 
         collection.bulkWrite(bulkOperations);
     }