DOCSP-33345: Java code comments pt. 2

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

@@ -1,3 +1,9 @@
+/**
+ * This file demonstrates how to find distinct values of a field by using the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and finds 
+ * distinct "year" values for documents that match the specified query filter.
+ */
+
 package usage.examples;
 
 import org.bson.Document;
@@ -17,17 +23,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 {
+                // Runs an operation that retrieves the distinct "year" values of matching documents
                 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 the operation generates an error
             } catch (MongoException me) {
                 System.err.println("An error occurred: " + me);
             }

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

@@ -1,3 +1,11 @@
+/**
+ * This file demonstrates how to find multiple documents by using the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and finds
+ * documents in the "movies" collection that match the specified query filter.
+ * The code projects certain fields in the returned documents and sorts them according to
+ * specified criteria.
+ */
+
 package usage.examples;
 
 import static com.mongodb.client.model.Filters.lt;
@@ -20,18 +28,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());
 
+            // Runs a find operation that matches documents with a "runtime" value under 15
             MongoCursor<Document> cursor = collection.find(lt("runtime", 15))
                     .projection(projectionFields)
                     .sort(Sorts.descending("title")).iterator();
 
+            // Prints two fields of each matching document and sorts the result documents
             try {
                 while(cursor.hasNext()) {
                     System.out.println(cursor.next().toJson());

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

@@ -1,3 +1,10 @@
+/**
+ * This file demonstrates how to find a document by using the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and finds
+ * a document in the "movies" collection that matches the specified query filter.
+ * The code projects certain fields in the returned document.
+ */
+
 package usage.examples;
 
 import static com.mongodb.client.model.Filters.eq;
@@ -20,19 +27,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());
 
+            // Runs a find operation that retrieves only the first matching document
             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 two fields of the matched document
             if (doc == null) {
                 System.out.println("No results found.");
             } else {

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

@@ -1,3 +1,10 @@
+/**
+ * This file demonstrates how to insert multiple documents into a collection by
+ * using the Java driver.
+ * The file connects to a MongoDB deployment, accesses the "sample_mflix" database,
+ * and inserts two new documents into the "movies" collection.
+ */
+
 package usage.examples;
 
 import java.util.Arrays;
@@ -19,18 +26,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 {
+                // Runs a write operation that inserts sample documents 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 the operation generates an error
             } 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,10 @@
+/**
+ * This file demonstrates how to insert a document into a collection by using the
+ * Java driver.
+ * The file connects to a MongoDB deployment, accesses the "sample_mflix" database,
+ * and inserts a new document into the "movies" collection.
+ */
+
 package usage.examples;
 
 import java.util.Arrays;
@@ -18,17 +25,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 {
+                // Runs a write operation that inserts a sample document 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 the operation generates an error
             } catch (MongoException me) {
                 System.err.println("Unable to insert due to an error: " + me);
             }