DOCSP-36852: cleanup fy2025q1 (#525)

* DOCSP-36852: cleanup fy2025q1

* vale

* vale

* fix indent

* MW PR fixes 1

* vale

Author: rustagir

source/compatibility.txt

@@ -55,5 +55,5 @@ The first column lists the driver version.
 
 .. include:: /includes/language-compatibility-table-java.rst
 
-For more information on how to read the compatibility tables, see our guide on
+For more information about how to read the compatibility tables, see our guide on
 :ref:`MongoDB Compatibility Tables. <about-driver-compatibility>`

source/connection-troubleshooting.txt

@@ -159,10 +159,11 @@ Connection Troubleshooting
 Security Certificate Errors
 ---------------------------
 
-If you use Java version 8 or earlier, you might need to add a certificate to
-your trust store. You can either upgrade to a later version of the JDK or read
-the :atlas:`Security FAQ </reference/faq/security/#java-users>` instructions
-in the Atlas documentation for information on how to add the certificate.
+If you use Java version 8 or earlier, you might need to add a
+certificate to your trust store. You can either upgrade to a later
+version of the JDK or read the :atlas:`Security FAQ
+</reference/faq/security/#java-users>` instructions in the Atlas
+documentation for information on how to add the certificate.
 
 .. _java-timeout-errors:
 

source/faq.txt

@@ -32,13 +32,13 @@ introduced in Java 9.
 Which type of ``MongoClient`` should I use?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-New applications should generally use the
+New applications generally use the
 ``com.mongodb.client.MongoClient`` interface, which supports:
 
 - Configuration with ``MongoClientSettings`` and ``ConnectionString``.  You can create instances of this interface via factory methods defined in the ``com.mongodb.client.MongoClients`` class.
 - CRUD API using ``MongoDatabase``, and from there, ``MongoCollection``
 
-You should use the ``com.mongodb.MongoClient`` class if you require support for the legacy API, which supports:
+Use the ``com.mongodb.MongoClient`` class if you require support for the legacy API, which supports:
 
 - Configuration with ``MongoClientOptions`` and ``MongoClientURI``
 - CRUD API using ``DB``, and from there, ``DBCollection``.  You can access this API via the ``getDB()`` method.
@@ -65,7 +65,7 @@ tasks with the ``MongoClientSettings`` class:
 - :ref:`Add Listeners For Driver and Database Events <listener-mongo-client-settings-example>`
 - :ref:`Get the Default Codec Registry <get-default-codec-registry-example>`
 
-For more information on the ``MongoClientSettings`` class, see the
+For more information about the ``MongoClientSettings`` class, see the
 `API Documentation for MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__.
 
 .. _java-faq-connection-pool:
@@ -149,7 +149,7 @@ use as they are returned to the pool.
 How do I prevent the "java.lang.NoClassDefFoundError: com/mongodb/MongoClient" error?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You may encounter a ``java.lang.NoClassDefFoundError`` exception when your
+You might encounter a ``java.lang.NoClassDefFoundError`` exception when your
 Java runtime environment cannot locate a class file at runtime. When you
 attempt to run application code that uses the {+driver-long+}, you must include
 the appropriate driver JAR files on the classpath.
@@ -166,7 +166,7 @@ your classpath, check the following items in your environment:
 .. tip::
 
    This error contains the package and class name, which can help you identify
-   which driver JAR may be missing from your classpath. To locate the
+   which driver JAR might be missing from your classpath. To locate the
    driver JAR that the error refers to, check each of the entries in the
    :ref:`API documentation <java-api-landing>`.
 
@@ -241,7 +241,7 @@ To learn more about the available builders classes, see the :ref:`<java-builders
 How do I prevent the "IllegalStateException: state should be: open" error?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You may encounter this exception if you call an operation on a ``MongoClient``
+You might encounter this exception if you call an operation on a ``MongoClient``
 instance that closed its connections to MongoDB. Once the ``close()`` method
 is called on the ``MongoClient``, any further operation calls on that instance
 throw this exception.
@@ -251,7 +251,7 @@ after any code that calls ``close()`` on it.
 
 .. tip::
 
-   The code that closes the ``MongoClient`` instance may be difficult to
+   The code that closes the ``MongoClient`` instance might be difficult to
    locate in certain cases. To locate potential sources of this exception,
    search for the following cases:
 
@@ -346,7 +346,7 @@ For example, the following methods throws an exception during encoding:
 How do I fix: "org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for class X."?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This exception means you need to register a codec for the class since
+This exception means you must register a codec for the class since
 there is none at the moment.
 
 How do I specify the collection name for a particular POJO class? Is there an annotation?
@@ -405,14 +405,14 @@ Imagine we are connecting to a collection that contains only this document:
          :start-after: start current-api-example
          :end-before: end current-api-example
 
-The output of the preceding code snippet should look like this:
+The output of the preceding code snippet resembles the following:
 
 .. code-block:: json
    :copyable: false
 
    {"_id": 1, "val": 1}
 
-For more information on the legacy classes and methods used in the preceding example,
+For more information about the legacy classes and methods used in the preceding example,
 see the following API documentation pages:
 
 - `MongoClient <{+api+}/apidocs/mongodb-driver-legacy/com/mongodb/MongoClient.html>`__
@@ -453,7 +453,7 @@ Here is an example showing how to use the legacy ``MongoClientOptions`` and
          :start-after: start current-api-mongoclientsettings-example
          :end-before: end current-api-mongoclientsettings-example
 
-For more information on the legacy classes and methods used in the preceding example,
+For more information about the legacy classes and methods used in the preceding example,
 see the following API Documentation pages:
 
 - `Legacy API documentation <{+api+}/apidocs/mongodb-driver-legacy/index.html>`__

source/fundamentals/aggregation-expression-operations.txt

@@ -42,7 +42,7 @@ imports in your code:
    import static com.mongodb.client.model.mql.MqlValues.*;
    import static java.util.Arrays.asList;
 
-To access document fields in an expression, you need to reference the
+To access document fields in an expression, you must reference the
 current document being processed by the aggregation pipeline. Use the
 ``current()`` method to refer to this document. To access the value of a
 field, you must use the appropriately typed method, such as
@@ -168,7 +168,7 @@ expressions.
    it literally. For example, ``of("$x")`` represents the string value
    ``"$x"``, rather than a field named ``x``.
 
-Refer to any of the sections in :ref:`Operations <java-aggregation-expression-ops-section>` for examples using these methods.
+See any of the sections in :ref:`Operations <java-aggregation-expression-ops-section>` for examples using these methods.
 
 .. _java-aggregation-expression-ops-section:
 
@@ -184,19 +184,19 @@ available in the driver and corresponding expression operators in the
 Query API. The method names link to API documentation and the
 aggregation pipeline operator names link to descriptions and examples in
 the Server manual documentation. While each Java method is effectively
-equivalent to the corresponding Query API expression, they may differ in
+equivalent to the corresponding Query API expression, they might differ in
 expected parameters and implementation.
 
 .. note::
 
-   The driver generates a Query API expression that may be different
+   The driver generates a Query API expression that might be different
    from the Query API expression provided in each example. However,
    both expressions will produce the same aggregation result.
 
 .. important::
 
    The driver does not provide methods for all aggregation pipeline operators in
-   the Query API. If you need to use an unsupported operation in an
+   the Query API. If you must use an unsupported operation in an
    aggregation, you must define the entire expression using the BSON ``Document``
    type. To learn more about the ``Document`` type, see :ref:`<fundamentals-documents>`.
 
@@ -389,7 +389,7 @@ with ``lt()``. The ``project()`` method stores these filtered results as a new
 .. tip::
 
    You must specify the type of the array that you retrieve with the
-   ``getArray()`` method if you need to work with the values of the
+   ``getArray()`` method if you work with the values of the
    array as their specific type.
 
    In this example, we specify that the ``seats`` array contains values
@@ -670,7 +670,7 @@ into custom static methods.
 
      - *No corresponding operator*
 
-Suppose you need to determine how a class is performing against some
+Suppose you want to determine how a class is performing against some
 benchmarks. You want to find the average final grade for each class and
 compare it against the benchmark values.
 
@@ -702,10 +702,10 @@ how the values compare:
 .. tip::
 
    One advantage of using the ``passTo()`` method is that you can reuse
-   your custom methods for other aggregations. You could
+   your custom methods for other aggregations. You can
    use the ``gradeAverage()`` method to find the average of grades for
    groups of students filtered by, for example, entry year or district, not just their
-   class. You could use the ``evaluate()`` method to evaluate, for
+   class. You can use the ``evaluate()`` method to evaluate, for
    example, an individual student's performance, or an entire school's or
    district's performance.
 
@@ -858,7 +858,7 @@ using the methods described in this section.
    * - `year() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/mql/MqlDate.html#year(com.mongodb.client.model.mql.MqlString)>`__
      - :manual:`$year </reference/operator/aggregation/year/>`
 
-Suppose you have data about package deliveries and need to match
+Suppose you have data about package deliveries and want to match
 deliveries that occurred on any Monday in the ``"America/New_York"`` time
 zone.
 
@@ -1125,7 +1125,7 @@ using the methods described in this section.
    * - `toUpper() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/mql/MqlString.html#toUpper()>`__
      - :manual:`$toUpper </reference/operator/aggregation/toUpper/>`
 
-Suppose you need to generate lowercase usernames for employees of a
+Suppose you want to generate lowercase usernames for employees of a
 company from the employees' last names and employee IDs.
 
 The ``append()`` method combines the ``firstName`` and ``lastName`` fields into

source/fundamentals/aggregation.txt

@@ -61,7 +61,7 @@ Aggregation operations have some :manual:`limitations </core/aggregation-pipelin
 - Returned documents must not violate the :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
   of 16 megabytes.
 
-- Pipeline stages have a memory limit of 100 megabytes by default. If required, you may exceed this limit by using
+- Pipeline stages have a memory limit of 100 megabytes by default. If required, you can exceed this limit by using
   the `allowDiskUse <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html#allowDiskUse(java.lang.Boolean)>`__
   method.
 
@@ -154,7 +154,7 @@ In the following example, the aggregation pipeline:
    :start-after: begin aggregation basic
    :end-before: end aggregation basic
 
-The preceding aggregation should produce the following results:
+The preceding aggregation produces the following results:
 
 .. code-block:: none
    :copyable: false
@@ -264,7 +264,7 @@ first element in the ``categories`` field.
    :start-after: begin aggregation expression
    :end-before: end aggregation expression
 
-The preceding aggregation should produce the following results:
+The preceding aggregation produces the following results:
 
 .. code-block:: none
    :copyable: false

source/fundamentals/auth.txt

@@ -34,7 +34,7 @@ Edition are as follows:
 
 To authenticate using ``Kerberos`` or ``LDAP``, see the
 :doc:`Enterprise Authentication Mechanisms guide </fundamentals/enterprise-auth>`.
-For more information on establishing a connection to your MongoDB cluster,
+For more information about establishing a connection to your MongoDB cluster,
 read our :doc:`Connection Guide </fundamentals/connection>`.
 
 Specify an Authentication Mechanism
@@ -90,8 +90,8 @@ mechanism:
       :tabid: Connection String
 
       To specify the default authentication mechanism using a connection
-      string, omit the mechanism. Your code to instantiate a ``MongoClient``
-      should look something like this:
+      string, omit the mechanism. The code to instantiate a ``MongoClient``
+      resembles the following:
 
       .. code-block:: java
 
@@ -101,12 +101,12 @@ mechanism:
       :tabid: MongoCredential
 
       To specify the default authentication mechanism using the
-      ``MongoCredential`` class, use the ``createCredential()`` method. Your
-      code to instantiate a ``MongoClient`` should look something like this:
+      ``MongoCredential`` class, use the ``createCredential()`` method. The
+      code to instantiate a ``MongoClient`` resembles the following:
 
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-default.rst
 
-For more information on the challenge-response (CR) and salted
+For more information about the challenge-response (CR) and salted
 challenge-response authentication mechanisms (SCRAM) that MongoDB supports,
 see the :manual:`SCRAM </core/security-scram/>` section of the {+mdb-server+}
 manual.
@@ -152,8 +152,8 @@ mechanism:
 
       To specify the ``SCRAM-SHA-256`` authentication mechanism using a
       connection string, assign the ``authMechanism`` parameter the value
-      ``SCRAM-SHA-256`` in your connection string. Your code to instantiate
-      a ``MongoClient`` should look something like this:
+      ``SCRAM-SHA-256`` in your connection string. The code to instantiate
+      a ``MongoClient`` resembles the following:
 
       .. code-block:: java
 
@@ -165,7 +165,8 @@ mechanism:
       To specify the default authentication mechanism using the
       ``MongoCredential`` class, use the
       `createScramSha256Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha256Credential(java.lang.String,java.lang.String,char[])>`__
-      method. Your code to instantiate a ``MongoClient`` should look something like this:
+      method. The code to instantiate a ``MongoClient`` resembles
+      the following:
 
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-sha256.rst
 
@@ -209,8 +210,8 @@ mechanism:
 
       To specify the ``SCRAM-SHA-1`` authentication mechanism using a
       connection string, assign the ``authMechanism`` parameter the value
-      ``SCRAM-SHA-1`` in your connection string. Your code to instantiate
-      a ``MongoClient`` should look something like this:
+      ``SCRAM-SHA-1`` in your connection string. The code to instantiate
+      a ``MongoClient`` resembles the following:
 
       .. code-block:: java
 
@@ -222,7 +223,7 @@ mechanism:
       To specify the default authentication mechanism using the
       ``MongoCredential`` class, use the
       `createScramSha1Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__
-      method. Your code to instantiate a ``MongoClient`` should look something like this:
+      method. The code to instantiate a ``MongoClient`` resembles the following:
 
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-sha1.rst
 
@@ -463,7 +464,7 @@ for ``MONGODB-AWS`` authentication,  use the `createAwsCredential() <{+api+}/api
 factory method.
 
 You can supply only programmatic access keys to the
-``MongoCredential.createAwsCredential()`` method. If you need to supply ECS
+``MongoCredential.createAwsCredential()`` method. If you must supply ECS
 or EC2 container credentials, use the instructions in
 :ref:`<java-mongodb-aws-env-variables>` or :ref:`<java-mongodb-aws-sdk>`.
 
@@ -485,7 +486,7 @@ in the following example:
    :end-before: end mongoCredential
    :emphasize-lines: 1
 
-If you need to specify an AWS session token, pass it to the
+If you must specify an AWS session token, pass it to the
 `withMechanismProperty() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#withMechanismProperty(java.lang.String,T)>`__
 method as shown in the following example:
 
@@ -549,8 +550,8 @@ mechanism:
       To specify the ``X.509`` authentication mechanism using a connection
       string, assign the ``authMechanism`` parameter the value ``MONGODB-X509``
       and enable TLS by assigning the ``tls``
-      parameter a ``true`` value. Your code to instantiate a ``MongoClient``
-      should look something like this:
+      parameter a ``true`` value. The code to instantiate a ``MongoClient``
+      resembles the following:
 
       .. code-block:: java
 
@@ -566,7 +567,8 @@ mechanism:
       `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__
       method and setting the ``enabled`` property to ``true`` in the
       `SslSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SslSettings.Builder.html>`__
-      block. Your code to instantiate a ``MongoClient`` should look something like this:
+      block. The code to instantiate a ``MongoClient`` resembles
+      the following:
 
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-x509.rst
 

source/fundamentals/builders/aggregates.txt

@@ -31,7 +31,7 @@ discoverable, typesafe Java methods to use in your aggregations, see
 
 .. tip::
 
-   For brevity, you may choose to import the methods of the following
+   For brevity, you can choose to import the methods of the following
    classes statically to make your queries more succinct:
 
    - ``Aggregates``
@@ -852,7 +852,7 @@ actions on these documents:
 - Group the documents by the ``position`` field.
 
 The call to the ``densify()`` aggregation stage builder that accomplishes
-these actions should resemble the following:
+these actions resembles the following:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateDensify.java
    :start-after: // begin densify aggregate

source/fundamentals/builders/filters.txt

@@ -55,7 +55,7 @@ type, which you can pass to any method that expects a query filter.
 
 .. tip::
 
-   For brevity, you may choose to import all methods of the
+   For brevity, you can choose to import all methods of the
    `Filters <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Filters.html>`__
    class statically: 
 

source/fundamentals/builders/indexes.txt

@@ -39,7 +39,7 @@ instance, which you can pass to
 
 .. tip::
 
-   For brevity, you may choose to import all methods of the
+   For brevity, you can choose to import all methods of the
    `Indexes <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Indexes.html>`__
    class statically: