DOCSP-33345: Java comments pt. 5 (#473)

* DOCSP-33345: Java comments pt. 5

* indicative mood

* review feedback

* sheet syntax

* final feedback

(cherry picked from commit e14a975)

Author: norareidy

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

@@ -19,6 +19,7 @@ public class CurrentAPI {
 
     public static void main(String[] args) throws InterruptedException {
         CurrentAPI c = new CurrentAPI();
+
         c.example1();
         c.example2();
 
@@ -29,13 +30,16 @@ private void example1() {
         MongoClient client = MongoClients.create(URI);
         MongoDatabase db = client.getDatabase(DATABASE);
         MongoCollection<Document> col = db.getCollection(COLLECTION);
+
+        // Prints the first document retrieved from the collection as JSON 
         Document doc = col.find().first();
         System.out.println(doc.toJson());
         // end current-api-example
         client.close();
     }
 
     private void example2() {
+        // Creates a MongoClient that requests write acknowledgement from at least one node
         // start current-api-mongoclientsettings-example
         MongoClientSettings options = MongoClientSettings.builder()
                 .applyConnectionString(new ConnectionString(URI))

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

@@ -59,27 +59,31 @@ public static void main(String [] args){
     }
 
     private void forEachIteration(){
+        // Prints the JSON representation of all documents in the collection
         // begin forEachIteration
         FindIterable<Document> iterable = collection.find();
         iterable.forEach(doc -> System.out.println(doc.toJson()));
         // end forEachIteration
     }
 
     private void firstExample(){
+        // Prints the first document that matches the query
         // begin firstExample
         FindIterable<Document> iterable = collection.find();
         System.out.println(iterable.first());
         // end firstExample
     }
 
     private void availableExample(){
+        // Prints the number of query results that are available in the returned cursor
         // begin availableExample
         MongoCursor<Document> cursor = collection.find().cursor();
         System.out.println(cursor.available());
         // end availableExample
     }
 
     private void explainExample(){
+        // Prints information about your find operation winning execution plan
         // begin explainExample
         Document explanation = collection.find().explain(ExplainVerbosity.EXECUTION_STATS);
         List<String> keys = Arrays.asList("queryPlanner", "winningPlan");
@@ -88,6 +92,7 @@ private void explainExample(){
     }
 
     private void intoExample(){
+        // Prints the results of the find operation as a list
         // begin intoExample
         List<Document> results = new ArrayList<>();
         FindIterable<Document> iterable = collection.find();
@@ -97,6 +102,7 @@ private void intoExample(){
     }
 
     private void manualIteration(){
+        // Prints the results of the find operation by iterating through a cursor
         // begin manualIteration
         MongoCursor<Document> cursor = collection.find().cursor();
         while (cursor.hasNext()){
@@ -106,6 +112,7 @@ private void manualIteration(){
     }
 
     private void closeExample(){
+        // Ensures the cursor frees up its resources after printing the documents it retrieved
         // begin closeExample
         MongoCursor<Document> cursor = collection.find().cursor();
 
@@ -120,6 +127,7 @@ private void closeExample(){
     }
 
     private void tryWithResourcesExample(){
+        // Frees up a cursor's consumption of resources automatically with a try statement
         // begin tryWithResourcesExample
         try(MongoCursor<Document> cursor = collection.find().cursor()) {
             while (cursor.hasNext()){
@@ -131,6 +139,7 @@ private void tryWithResourcesExample(){
 
     public void setupPaintCollection(){
         collection.drop();
+
         collection.insertMany(Arrays.asList(
             new Document("_id", 1).append("color", "red").append("qty", 5), 
             new Document("_id", 2).append("color", "purple").append("qty", 10), 

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

@@ -52,35 +52,41 @@ public static void main(String [] args){
     }
 
     private void deleteManyExample(){
+        // Deletes all documents in the collection that contain a "qty" value of 0
         // begin deleteManyExample
         Bson filter = Filters.eq("qty", 0);
         collection.deleteMany(filter);
         // end deleteManyExample
     }
 
     private void findOneAndDeleteExample(){
+        // Deletes the first document with a "color" value of "purple" and prints the deleted document
         // begin findOneAndDeleteExample
-        Bson filter = Filters.eq("color", purple);
+        Bson filter = Filters.eq("color", "purple");
         System.out.println(collection.findOneAndDelete(filter).toJson());
         // end findOneAndDeleteExample
     }
 
     private void findOneAndDeleteNullExample(){
+        // Deletes the first document with a "qty" value of 1 and prints the deleted document
         // begin findOneAndDeleteNullExample
         Bson filter = Filters.eq("qty", 1);
         System.out.println(collection.findOneAndDelete(filter));
         // end findOneAndDeleteNullExample
     }
 
     private void deleteOneExample(){
+        // Deletes the first document with a "color" value of "yellow"
         // begin deleteOneExample
         Bson filter = Filters.eq("color", "yellow");
         collection.deleteOne(filter);
         // end deleteOneExample
     }
     private void preview(boolean drop){
+        // Prints all documents in a collection as JSON
         Bson filter = Filters.empty();
         collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));
+        
         if (drop){
           collection.drop();  
         }

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

@@ -65,34 +65,39 @@ public static void main(String[] args) {
     }
 
     private void equalComparison() {
+        // Prints all documents in a collection that have a "qty" value of "5" as JSON
         // begin equalComparison
         Bson equalComparison = eq("qty", 5);
         collection.find(equalComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end equalComparison
     }
 
     private void gteComparison() {
+        // Prints all documents in a collection that have a "qty" value greater than "10" as JSON
         // begin gteComparison
         Bson gteComparison = gte("qty", 10);
         collection.find(gteComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end gteComparison
     }
 
     private void orComparison() {
+        // Prints all documents in a collection that have a "qty" value of "8" or a "color" value of "pink" as JSON
         // begin orComparison
         Bson orComparison = or(gt("qty", 8), eq("color", "pink"));
         collection.find(orComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end orComparison
     }
 
     private void emptyComparison() {
+        // Prints all documents in a collection as JSON
         // begin emptyComparison
         Bson emptyComparison = empty();
         collection.find(emptyComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end emptyComparison
     }
 
     private void allComparison() {
+        // Prints all documents in which the "vendor" field contains all the elements of a list as JSON
         // begin allComparison
         List<String> search = Arrays.asList("A", "D");
         Bson allComparison = all("vendor", search);
@@ -101,20 +106,23 @@ private void allComparison() {
     }
 
     private void existsComparison() {
+        // Prints documents in which a "qty" field exists and the value is not "5" or "8" as JSON
         // begin existsComparison
         Bson existsComparison = and(exists("qty"), nin("qty", 5, 8));
         collection.find(existsComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end existsComparison
     }
 
     private void regexComparison() {
+        // Prints all documents in which the "color" field value starts with "p" as JSON
         // begin regexComparison
         Bson regexComparison = regex("color", "^p");
         collection.find(regexComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end regexComparison
     }
 
     private void bitsComparison() {
+        // Prints all documents that contain values in a field called "a" that match the bitmask value of "34"
         // begin bitsComparison
         Bson bitsComparison = bitsAllSet("a", 34);
         collection.find(bitsComparison).forEach(doc -> System.out.println(doc.toJson()));
@@ -129,6 +137,7 @@ private void geoWithinComparison() {
                                             new Position(0, 4),
                                             new Position(0, 0)));
 
+        // Prints documents that contain "coordinates" values that are within the bounds of the polygon passed as the filter parameter
         Bson geoWithinComparison = geoWithin("coordinates", square);
         collection.find(geoWithinComparison).forEach(doc -> System.out.println(doc.toJson()));
         // end geoWithinComparison
@@ -144,6 +153,7 @@ private void preview(){
     private void setupPaintCollection() {
 
         List<Document> filterdata = new ArrayList<>();
+
         String [] p1a = {"A"};
         String [] p2a = {"C", "D"};
         String [] p3a = {"B","A"};

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

@@ -46,12 +46,19 @@ public void go() {
     private void nearExample() {
         // begin findExample
 
-        // code to set up your mongo client ...
+        // Add your MongoClient setup code here
         MongoDatabase database = mongoClient.getDatabase("sample_mflix");
         MongoCollection<Document> collection = database.getCollection("theaters");
+
         Point centralPark = new Point(new Position(-73.9667, 40.78));
+        
+        // Creates a query that matches all locations between 5,000 and 10,000 meters from the specified Point
         Bson query = near("location.geo", centralPark, 10000.0, 5000.0);
+
+        // Creates a projection to include only the "location.address.city" field in the results
         Bson projection = fields(include("location.address.city"), excludeId());
+        
+        // Prints the projected field of the results from the geospatial query as JSON
         collection.find(query)
                 .projection(projection)
                 .forEach(doc -> System.out.println(doc.toJson()));
@@ -62,14 +69,21 @@ private void rangeExample() {
         MongoDatabase database = mongoClient.getDatabase("sample_mflix");
         MongoCollection<Document> collection = database.getCollection("theaters");
         // begin rangeExample
+        // Add your MongoCollection setup code here
 
-        // code to set up your mongo collection ...
+        // Creates a set of points that defines the bounds of a geospatial shape
         Polygon longIslandTriangle = new Polygon(Arrays.asList(new Position(-72, 40),
                 new Position(-74, 41),
                 new Position(-72, 39),
                 new Position(-72, 40)));
+
+        // Creates a projection to include only the "location.address.city" field in the results
         Bson projection = fields(include("location.address.city"), excludeId());
+
+        // Creates a query that matches documents containing "location.geo" values within the specified bounds
         Bson geoWithinComparison = geoWithin("location.geo", longIslandTriangle);
+        
+        // Prints the projected field of the results from the geolocation query as JSON
         collection.find(geoWithinComparison)
                 .projection(projection)
                 .forEach(doc -> System.out.println(doc.toJson()));