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,21 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
+            // Access the "movies" collection in the "sample_mflix" database
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             try {
+                // Find distinct "year" values for movies directed by "Carl Franklin"
                 DistinctIterable<Integer> docs = collection.distinct("year", Filters.eq("directors", "Carl Franklin"), Integer.class);
                 MongoCursor<Integer> results = docs.iterator();
 
+                // Iterate through the distinct "year" values and print them
                 while(results.hasNext()) {
                     System.out.println(results.next());
                 }
+
+            // Handle any exceptions that might 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,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,21 @@ public static void main( String[] args ) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
+            // Access the "movies" collection in the "sample_mflix" database
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Define a projection to include the "title" and "imdb" fields and exclude "_id"
             Bson projectionFields = Projections.fields(
                     Projections.include("title", "imdb"),
                     Projections.excludeId());
 
+            // Find documents that have a "runtime" value less than 15, apply the projection, and sort the results
             MongoCursor<Document> cursor = collection.find(lt("runtime", 15))
                     .projection(projectionFields)
                     .sort(Sorts.descending("title")).iterator();
 
+            // Iterate through the returned documents and print them
             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,22 @@ public static void main( String[] args ) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
+            // Access the "movies" collection in the "sample_mflix" database
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Define a projection to include the "title" and "imdb" fields and exclude "_id"
             Bson projectionFields = Projections.fields(
                     Projections.include("title", "imdb"),
                     Projections.excludeId());
 
+            // Find documents with a "title" of "The Room", apply the projection, sort, and retrieve the first match
             Document doc = collection.find(eq("title", "The Room"))
                     .projection(projectionFields)
                     .sort(Sorts.descending("imdb.rating"))
                     .first();
 
+            // Print the returned document, or print that none were found
             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,23 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
+            // Access the "movies" collection in the "sample_mflix" database
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Define a list of documents to insert
             List<Document> movieList = Arrays.asList(
                     new Document().append("title", "Short Circuit 3"),
                     new Document().append("title", "The Lego Frozen Movie"));
 
             try {
+                // Insert the documents into the collection
                 InsertManyResult result = collection.insertMany(movieList);
 
+                // Print the IDs of the inserted documents
                 System.out.println("Inserted document ids: " + result.getInsertedIds());
+
+            // Handle any exceptions that might 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,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,21 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
+            // Access the "movies" collection in the "sample_mflix" database
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             try {
+                // Create a document to insert
                 InsertOneResult result = collection.insertOne(new Document()
                         .append("_id", new ObjectId())
                         .append("title", "Ski Bloopers")
                         .append("genres", Arrays.asList("Documentary", "Comedy")));
 
+                // Print the ID of the inserted document
                 System.out.println("Success! Inserted document id: " + result.getInsertedId());
+
+            // Handle any exceptions that might occur during the operation
             } catch (MongoException me) {
                 System.err.println("Unable to insert due to an error: " + me);
             }