DOCSP-33345: Java code comments pt. 2 (#470)

* DOCSP-33345: Java code comments pt. 2

* CC edits

* CD feedback + sheet syntax

Author: norareidy

source/includes/usage-examples/code-snippets/Distinct.java

@@ -1,3 +1,5 @@
+// Retrieves distinct values of a field by using the Java driver
+
 package usage.examples;
 
 import org.bson.Document;
@@ -17,17 +19,20 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             try {
+                // Retrieves the distinct values of the "year" field present in documents that match the filter
                 DistinctIterable<Integer> docs = collection.distinct("year", Filters.eq("directors", "Carl Franklin"), Integer.class);
                 MongoCursor<Integer> results = docs.iterator();
 
+                // Prints the distinct "year" values
                 while(results.hasNext()) {
                     System.out.println(results.next());
                 }
+
+            // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {
                 System.err.println("An error occurred: " + me);
             }

source/includes/usage-examples/code-snippets/Find.java

@@ -1,3 +1,5 @@
+// Retrieves documents that match a query filter by using the Java driver
+
 package usage.examples;
 
 import static com.mongodb.client.model.Filters.lt;
@@ -20,18 +22,20 @@ public static void main( String[] args ) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Creates instructions to project two document fields
             Bson projectionFields = Projections.fields(
                     Projections.include("title", "imdb"),
                     Projections.excludeId());
 
+            // Retrieves documents that match the filter, applying a projection and a descending sort to the results
             MongoCursor<Document> cursor = collection.find(lt("runtime", 15))
                     .projection(projectionFields)
                     .sort(Sorts.descending("title")).iterator();
 
+            // Prints the results of the find operation as JSON
             try {
                 while(cursor.hasNext()) {
                     System.out.println(cursor.next().toJson());

source/includes/usage-examples/code-snippets/FindOne.java

@@ -1,3 +1,5 @@
+// Retrieves a document that matches a query filter by using the Java driver
+
 package usage.examples;
 
 import static com.mongodb.client.model.Filters.eq;
@@ -20,19 +22,21 @@ public static void main( String[] args ) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Creates instructions to project two document fields
             Bson projectionFields = Projections.fields(
                     Projections.include("title", "imdb"),
                     Projections.excludeId());
 
+            // Retrieves the first matching document, applying a projection and a descending sort to the results
             Document doc = collection.find(eq("title", "The Room"))
                     .projection(projectionFields)
                     .sort(Sorts.descending("imdb.rating"))
                     .first();
 
+            // Prints a message if there are no result documents, or prints the result document as JSON
             if (doc == null) {
                 System.out.println("No results found.");
             } else {

source/includes/usage-examples/code-snippets/InsertMany.java

@@ -1,3 +1,5 @@
+// Inserts sample documents describing movies by using the Java driver
+
 package usage.examples;
 
 import java.util.Arrays;
@@ -19,18 +21,22 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Creates two sample documents containing a "title" field
             List<Document> movieList = Arrays.asList(
                     new Document().append("title", "Short Circuit 3"),
                     new Document().append("title", "The Lego Frozen Movie"));
 
             try {
+                // Inserts sample documents describing movies into the collection
                 InsertManyResult result = collection.insertMany(movieList);
 
+                // Prints the IDs of the inserted documents
                 System.out.println("Inserted document ids: " + result.getInsertedIds());
+            
+            // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {
                 System.err.println("Unable to insert due to an error: " + me);
             }

source/includes/usage-examples/code-snippets/InsertOne.java

@@ -1,3 +1,5 @@
+// Inserts a sample document describing a movie by using the Java driver
+
 package usage.examples;
 
 import java.util.Arrays;
@@ -18,17 +20,20 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             try {
+                // Inserts a sample document describing a movie into the collection
                 InsertOneResult result = collection.insertOne(new Document()
                         .append("_id", new ObjectId())
                         .append("title", "Ski Bloopers")
                         .append("genres", Arrays.asList("Documentary", "Comedy")));
 
+                // Prints the ID of the inserted document
                 System.out.println("Success! Inserted document id: " + result.getInsertedId());
+            
+            // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {
                 System.err.println("Unable to insert due to an error: " + me);
             }