DOCSP-33345: Java comments pt. 7 (#476)

* DOCSP-33345: Java comments pt. 7

* more comments

* reword

(cherry picked from commit 4831458)

Author: norareidy

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

@@ -29,23 +29,33 @@ public static void main(String[] args) {
 
             try {
                 ObjectId testId = new ObjectId("507f1f77bcf86cd799439013");
+
+                // Creates a document that has a specified "_id" value
                 Document idDocument = new Document().append("_id", testId);
 
+                // Deletes a document that has a specified "_id" value and inserts a document with the same "_id" value
                 collection.deleteOne(idDocument);
                 collection.insertOne(new Document()
                             .append("_id", testId)
                             .append("createdAt", new Date())
                             .append("myNumber", 36520312L));
+
+                // Retrieves the first document that has the specified "_id" value
                 Document doc = collection.find(idDocument)
                         .first();
 
+                // Prints the result of the find operation in multiple JSON formats
                 for (JsonMode mode : modes) {
                     JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(mode).build();
                     System.out.println(mode.name() + ":" + doc.toJson(settings));
                 }
+
+            // Prints exception details if any exceptions occur during the find operation
             } catch (MongoException me) {
                 System.err.println(me);
             }
+
+        // Prints exception details if any exceptions occur during the client and dataset setup
         } catch (Exception e) {
             System.err.println(e);
         }

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

@@ -15,17 +15,21 @@ public static void main(String[] args) {
     }
 
     private void example1() {
+        // Connects to a MongoDB instance with the legacy API
         // start legacy-api-example
         MongoClient client = new MongoClient(URI);
         DB db = client.getDB(DATABASE);
         DBCollection col = db.getCollection(COLLECTION);
+
+        // Retrieves one document in the collection and prints it
         DBObject doc = col.find().one();
         System.out.println(doc.toString());
         // end legacy-api-example
         client.close();
     }
 
     private void example2() {
+        // Creates a MongoClient with the legacy API that requests write acknowledgement from at least one node
         // start legacy-api-mongoclientoptions-example
         MongoClientURI mongoURI = new MongoClientURI(URI,
                 MongoClientOptions.builder()

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

@@ -18,32 +18,38 @@ public class MongoDbAwsAuth {
     // Placeholder functions
 
     private static void encodeText() throws UnsupportedEncodingException {
+        // Defines the encoding scheme used to translate a string
         // start urlEncode
         String encodedField = java.net.URLEncoder.encode("<fieldValue>".toString(), "ISO-8859-1");
         // end urlEncode
     }
     private static void connectionString() {
+        // Creates a MongoClient and provides AWS credentials to enable the MONGODB-AWS authentication mechanism
         // start connectionString
         MongoClient mongoClient = MongoClients.create("mongodb://<awsKeyId>:<awsSecretKey>@<atlasUri>?authMechanism=MONGODB-AWS");
         // end connectionString
     }
 
     private static void mechOnlyConnectionString() {
+        // Creates a MongoClient that MongoDB authenticates by using the MONGODB-AWS mechanism
         // start mechOnlyConnectionString
         MongoClient mongoClient = MongoClients.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS");
         // end mechOnlyConnectionString
     }
 
     private static void connectionStringSessionToken() {
+        // Creates a MongoClient and provides AWS credentials and a session token to enable the MONGODB-AWS authentication mechanism
         // start connectionStringSessionToken
         MongoClient mongoClient = MongoClients.create("mongodb://<awsKeyId>:<awsSecretKey>@<atlasUri>?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");
         // end connectionStringSessionToken
     }
 
     private static void mongoCredential() {
+        // Creates a MongoCredential instance to specify the AWS credentials
         // start mongoCredential
         MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
 
+        // Creates a MongoClient that receives AWS credentials from the MongoCredential instance
         MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder()
                 .applyToClusterSettings(builder ->
@@ -54,9 +60,11 @@ private static void mongoCredential() {
     }
 
     private static void mechOnlyMongoCredential() {
+        // Creates a MongoCredential instance to specify the authentication mechanism
         // start mechOnlyMongoCredential
         MongoCredential credential = MongoCredential.createAwsCredential(null, null);
 
+        // Creates a MongoClient that receives configuration information from a MongoCredential and environment variables
         MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder()
                 .applyToClusterSettings(builder ->
@@ -67,10 +75,14 @@ private static void mechOnlyMongoCredential() {
     }
 
     private static void mongoCredentialSessionTokenConnString() {
+        // Creates a MongoCredential instance to specify the AWS credentials
         // start mongoCredentialSessionTokenConnString
         MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray());
+
+        // Specifies the authentication mechanism and session token in a connection string
         ConnectionString connectionString = new ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");
 
+        // Creates a MongoClient that receives configuration information from a MongoCrediential and connection string
         MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder()
                 .applyConnectionString(connectionString)
@@ -80,9 +92,11 @@ private static void mongoCredentialSessionTokenConnString() {
     }
 
     private static void mongoCredentialSessionTokenCredential() {
+        // Creates a MongoCredential instance to specify the AWS credentials and a session token
         // start mongoCredentialSessionTokenCredential
         MongoCredential credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray()).withMechanismProperty("AWS_SESSION_TOKEN",  "<awsSessionToken>");
 
+         // Creates a MongoClient that receives configuration information from a MongoCredential instance
         MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder()
                 .applyToClusterSettings(builder ->
@@ -93,23 +107,26 @@ private static void mongoCredentialSessionTokenCredential() {
     }
 
     private static void mongoCredentialECSorEC2() {
+        // Creates a MongoCredential instance to specify the authentication mechanism
         // start mongoCredentialECSorEC2
         MongoCredential credential = MongoCredential.createAwsCredential(null, null);
         // end mongoCredentialECSorEC2
     }
 
     private static void refreshCredentials() {
-
+        // Creates a lambda expression that returns new AWS credentials
         // start refreshCredentials
         Supplier<AwsCredential> awsFreshCredentialSupplier = () -> {
-            // Add your code here to fetch new credentials here
+            // Add your code to fetch new credentials
 
-            // Return the new credentials
             return new AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>");
         };
 
+        // Creates a MongoCredential instance to specify the new AWS credentials
         MongoCredential credential = MongoCredential.createAwsCredential(null, null)
                 .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier);
+
+        // Creates a MongoClient that receives new configuration information from a MongoCredential instance
         MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder()
                 .applyToClusterSettings(builder ->