RM PR fixes 1

Author: rustagir

source/fundamentals/builders.txt

@@ -24,13 +24,13 @@ Overview
 --------
 
 This section includes guides on how to use each of the available
-builders and demonstrates the utility that the {+driver-short} builder
+builders and demonstrates the utility that the {+driver-short+} builder
 classes provide. 
 
-The {+driver-short} provides classes to simplify the process of
-performing CRUD operations and the Aggregation API. The static utility
-methods allow you to build queries and other kinds of documents more
-efficiently.
+The {+driver-short+} provides classes to simplify the process of
+performing CRUD operations and using the Aggregation API. The static
+utility methods allow you to build queries and other kinds of documents
+more efficiently.
 
 Why Use Builders?
 -----------------
@@ -46,10 +46,10 @@ the MongoDB shell or plain {+language+} instead, you write operators as
 strings and get no visual indication of a problem, which pushes these
 errors to runtime instead of compile time.
 
-By using builder classes, you cab write operators as methods. The IDE
-instantly indicates whether your code has errors. While developing, the
-IDE also shows you the methods you can use and can complete your code with
-placeholder parameters.
+By using builder classes, you can write operators as methods, so that
+your IDE instantly indicates whether your code has errors. While
+developing, your IDE can also show you methods that you can use and can
+complete your code with placeholder parameters.
 
 Example Scenario
 ----------------
@@ -60,8 +60,7 @@ collection that meet the following criteria:
 - Users in which the value of the ``gender`` field is ``"female"``
 - Users in which the value of the ``age`` field is greater than ``29``
 
-You only want their email addresses, so your query won't
-return data that you don't need.
+You also need your query to return only their email addresses.
 
 The documents in the ``users`` collection are modeled by the following
 data class:
@@ -88,6 +87,10 @@ builders in the {+driver-short+}:
 .. literalinclude:: /examples/generated/BuildersTest.snippet.no-builders.kt
    :language: kotlin
 
+In this case, you could easily include an error when writing the
+``"\$gt"`` operator in the filter, but you would see an error only at
+runtime.
+
 Using Builders
 ~~~~~~~~~~~~~~
 

source/fundamentals/builders/aggregates.txt

@@ -54,13 +54,7 @@ modeled by the following ``Movie`` data class for use with the Kotlin driver:
 .. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.movie-data-class.kt
    :language: kotlin
 
-.. tip:: Aggregates and Data Class Properties
-
-   You can use methods from the ``Aggregates`` and
-   ``Accumulators`` classes directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 Match
 -----

source/fundamentals/builders/builders-data-classes.txt

@@ -77,10 +77,9 @@ dependency to your project by using the :guilabel:`Gradle` and
 
 After you install the extensions dependency, you can use the extension
 methods by importing classes and methods from the
-``com.mongodb.kotlin.client.model`` path. You can access the standard
-builder classes and methods from the ``com.mongodb.client.model`` path,
-so you can mix calls that reference string field names and data
-class properties in the same application.
+``com.mongodb.kotlin.client.model`` path. You can mix usage of these methods and
+the standard builder methods in the same application, as shown in the
+:ref:`kotlin-data-class-aggregates` example in this guide.
 
 Builders Examples
 -----------------

source/fundamentals/builders/filters.txt

@@ -82,12 +82,7 @@ with the Kotlin driver:
 .. literalinclude:: /examples/generated/FiltersBuildersTest.snippet.paint-order-data-class.kt
     :language: kotlin
 
-.. tip:: Filters and Data Class Properties
-
-   You can use methods from the ``Filters`` class directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 .. _comparison:
 

source/fundamentals/builders/indexes.txt

@@ -45,12 +45,7 @@ instance, which you can pass to
 
       import com.mongodb.client.model.Indexes.*
 
-.. tip:: Indexes and Data Class Properties
-
-   You can use methods from the ``Indexes`` class directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 .. _ascending-indexes:
 

source/fundamentals/builders/projections.txt

@@ -95,12 +95,7 @@ The following data class is used to represent the documents in the collection:
 .. literalinclude:: /examples/generated/ProjectionsBuildersTest.snippet.example-data-class.kt
    :language: kotlin
 
-.. tip:: Projections and Data Class Properties
-
-   You can use methods from the ``Projections`` class directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 Projection Operations
 ---------------------

source/fundamentals/builders/sort.txt

@@ -53,12 +53,7 @@ This data is modeled with the following Kotlin data class:
 .. literalinclude:: /examples/generated/SortTest.snippet.sort-data-model.kt
    :language: kotlin
 
-.. tip:: Sorts and Data Class Properties
-
-   You can use methods from the ``Sorts`` class directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 The Sorts Class
 ---------------

source/fundamentals/builders/updates.txt

@@ -1,3 +1,5 @@
+.. _updates-builders:
+
 ================
 Updates Builders
 ================
@@ -15,8 +17,6 @@ Updates Builders
    :depth: 2
    :class: singlecol
 
-.. _updates-builders:
-
 Overview
 --------
 
@@ -68,12 +68,7 @@ This example is modeled by the following data class unless otherwise noted:
 .. literalinclude:: /examples/generated/UpdatesBuildersTest.snippet.example-data-class.kt
    :language: kotlin
 
-.. tip:: Updates and Data Class Properties
-
-   You can use methods from the ``Updates`` class directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 .. _field_updates:
 

source/fundamentals/data-formats/document-data-format-data-class.txt

@@ -60,12 +60,7 @@ as shown in the following code:
 
       DataStorage(productName=tape, capacity=5.0)
 
-.. tip:: Builders for Data Class Properties
-
-   You can use methods from builder classes directly with data class
-   properties by adding the optional {+driver-short+} extensions
-   dependency to your application. To learn more and view examples, see
-   the :ref:`kotlin-builders-data-classes` guide.
+.. include:: /includes/fundamentals/builders-dataclass.rst
 
 You specify a class for documents returned from a collection, even if it
 is different than the class you specified when retrieving the

source/includes/fundamentals/builders-dataclass.rst

@@ -0,0 +1,6 @@
+.. tip:: Builder Methods and Data Class Properties
+
+   You can use the methods from builder classes directly with data
+   class properties by adding the optional {+driver-short+} extensions
+   dependency to your application. To learn more and view examples, see
+   the :ref:`kotlin-builders-data-classes` guide.