AS PR fixes 1

Author: rustagir

source/write/replace.txt

@@ -27,10 +27,8 @@ removes all fields and values from a specified document except the
 operations differs from an update operation, which changes only
 specified fields in one or more documents.
 
-.. tip:: Learn About Update Operations
-
-   To learn more about update operations, see the
-   :ref:`kotlin-sync-write-update` guide.
+To learn more about update operations, see the
+:ref:`kotlin-sync-write-update` guide.
 
 Sample Data
 ~~~~~~~~~~~
@@ -85,9 +83,10 @@ value is ``"Primola Restaurant"``:
 
 .. important::
 
-   The values of ``_id`` fields are immutable. If your replacement document specifies
-   a value for the ``_id`` field, it must be the same as the ``_id`` value of the
-   existing document.
+   The values of ``_id`` fields are immutable. If your replacement
+   document specifies a value for the ``_id`` field, it must be the same
+   as the ``_id`` value of the existing document or the driver raises a
+   ``WriteError``.
 
 Customize the Replace Operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -141,13 +140,10 @@ configure an ``ReplaceOptions`` instance:
    * - ``comment()``
      - | Sets a comment to attach to the operation.
 
-The following code uses the ``replaceOne()`` method to match the first
-document in which the value of the ``name`` field is ``"Pizza Plus"``,
-then replaces the fields with new fields.
-
-Because the ``upsert`` option is set to ``true``, the driver inserts a
-new document that has the fields and values specified in the replacement
-document if the query filter doesn't match any existing documents.
+The following code sets the ``upsert`` option ``true``, instructing the
+driver to insert a new document that has the fields and values specified
+in the replacement document if the query filter doesn't match any
+existing documents:
 
 .. literalinclude:: /includes/write/replace.kt
    :start-after: start-replace-options
@@ -171,19 +167,19 @@ an ``UpdateResult`` instance:
      - Description
 
    * - ``getMatchedCount()``
-     - | Indicates the number of documents that matched the query filter, regardless of
+     - | Returns the number of documents that matched the query filter, regardless of
          how many updates were performed.
 
    * - ``getModifiedCount()``
-     - | Indicates number of documents modified by the update operation. If an updated
+     - | Returns the number of documents modified by the update operation. If an updated
          document is identical to the original, it is not included in this
          count.
 
    * - ``wasAcknowledged()``
      - | Returns ``true`` if the server acknowledged the result.
 
    * - ``getUpsertedId()``
-     - | Specifies the ``_id`` value of the document that was upserted
+     - | Returns the ``_id`` value of the document that was upserted
          in the database, if the driver performed an upsert.
 
 Additional Information 

source/write/update.txt

@@ -183,19 +183,19 @@ an ``UpdateResult`` instance:
      - Description
 
    * - ``getMatchedCount()``
-     - | Indicates the number of documents that matched the query filter, regardless of
+     - | Returns the number of documents that matched the query filter, regardless of
          how many updates were performed.
 
    * - ``getModifiedCount()``
-     - | Indicates number of documents modified by the update operation. If an updated
+     - | Returns the number of documents modified by the update operation. If an updated
          document is identical to the original, it is not included in this
          count.
 
    * - ``wasAcknowledged()``
      - | Returns ``true`` if the server acknowledged the result.
 
    * - ``getUpsertedId()``
-     - | Specifies the ``_id`` value of the document that was upserted
+     - | Returns the ``_id`` value of the document that was upserted
          in the database, if the driver performed an upsert.
 
 .. note::