DOCSP-16178 BACKPORT (#872)

Author: Dave

source/reference/method/db.collection.findOneAndReplace.txt

@@ -42,145 +42,130 @@ form:
         sort: <document>,
         maxTimeMS: <number>,
         upsert: <boolean>,
+        returnDocument: <string>,
         returnNewDocument: <boolean>,
         collation: <document>
       }
    )
 
-Parameters and Options
-~~~~~~~~~~~~~~~~~~~~~~
+Fields and Options
+~~~~~~~~~~~~~~~~~~
 
 The :method:`~db.collection.findOneAndReplace()` method takes the following
-parameters and options:
+fields and options:
 
 
 .. list-table::
    :header-rows: 1
    :widths: 20 20 80
 
-   * - Parameter
-
+   * - Field
      - Type
-
      - Description
 
    * - :ref:`filter <findOneAndReplace-filter>`
-
      - document
-
      - .. _findOneAndReplace-filter:
-     
+
        The selection criteria for the update. The same :ref:`query
        selectors <query-selectors>` as in the :method:`find()
        <db.collection.find()>` method are available.
-       
-       Specify an empty document ``{ }`` to replace the first document returned in 
-       the collection.
-       
+
+       To replace the first document returned in the collection,
+       specify an empty document ``{ }``.
+
        If unspecified, defaults to an empty document.
-       
-       Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation
-       errors if the query argument is not a document.
-       
-       
 
-   * - :ref:`replacement <findOneAndReplace-replacement>`
+       Starting in MongoDB 4.2, the operation returns an error if the
+       query argument is not a document.
 
+   * - :ref:`replacement <findOneAndReplace-replacement>`
      - document
-
      - .. _findOneAndReplace-replacement:
-     
+
        The replacement document.
-       
+
        Cannot contain 
-       :doc:`update operators</reference/operator/update>`.
-       
-       The ``<replacement>`` document cannot specify an ``_id`` value that differs 
-       from the replaced document.
-       
-       
+       :ref:`update operators <update-operators-top-level>`.
 
-   * - :ref:`projection <findOneAndReplace-projection>`
+       The ``<replacement>`` document cannot specify an ``_id`` value
+       that differs from the replaced document.
 
+   * - :ref:`projection <findOneAndReplace-projection>`
      - document
-
      - .. _findOneAndReplace-projection:
-     
+
        Optional. A subset of fields to return.
-       
-       To return all fields in the matching document, omit this parameter.
-       
-       Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation
-       errors if the projection argument is not a document.
-       
-       
 
-   * - :ref:`sort <findOneAndReplace-sort>`
+       To return all fields in the matching document, omit this
+       field.
 
-     - document
+       Starting in MongoDB 4.2, the operation returns an error if the
+       projection field is not a document.
 
+   * - :ref:`sort <findOneAndReplace-sort>`
+     - document
      - .. _findOneAndReplace-sort:
-     
-       Optional. Specifies a sorting order for the documents matched by the ``filter``.
+
+       Optional. Specifies a sorting order for the documents matched by
+       the :ref:`filter <findOneAndReplace-filter>`.
 
-       Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation
-       errors if the sort argument is not a document.
+       Starting in MongoDB 4.2, the operation returns an error if the
+       sort field is not a document.
 
        See :method:`cursor.sort()`.
-       
-       
 
    * - ``maxTimeMS``
-
      - number
-
-     - Optional. Specifies a time limit in milliseconds within which the operation must 
-       complete. Throws an error if the limit is exceeded.
-       
-       
+     - Optional. Specifies a time limit in milliseconds within which
+       the operation must complete. Returns an error if the limit is
+       exceeded.
 
    * - :ref:`upsert <findOneAndReplace-upsert>`
-
      - boolean
-
      - .. _findOneAndReplace-upsert:
 
        .. include:: /includes/extracts/findOneAndReplace-behavior-method.rst
-       
-       
 
-   * - :ref:`returnNewDocument <findOneAndReplace-returnNewDocument>`
+   * - :ref:`returnDocument <findOneAndReplace-returnDocument>`
+     - string
+     - .. _findOneAndReplace-returnDocument:
 
-     - boolean
+       Optional. Starting in :binary:`mongosh` 0.13.2,
+       ``returnDocument`` is an alternative for
+       :ref:`returnNewDocument <findOneAndReplace-returnNewDocument>`.
+       If both options are set, ``returnDocument`` takes precedence.
 
+       ``returnDocument: "before"`` returns the original document.
+       ``returnDocument: "after"`` returns the updated document.
+
+   * - :ref:`returnNewDocument <findOneAndReplace-returnNewDocument>`
+     - boolean
      - .. _findOneAndReplace-returnNewDocument:
 
-       Optional. When ``true``, returns the replacement document instead of the original 
-       document.
-       
+       Optional. When ``true``, returns the replacement document
+       instead of the original document.
+
        Defaults to ``false``.
-       
-       
 
-   * - :ref:`collation <findOneAndReplace-collation>`
 
+   * - :ref:`collation <findOneAndReplace-collation>`
      - document
-
      - .. _findOneAndReplace-collation:
 
        Optional. 
-       
+
        .. include:: /includes/extracts/collation-option.rst
-       
-       
 
 
 Returns
 ~~~~~~~
 
-Returns either the original document or, if :ref:`returnNewDocument:
-true <findOneAndReplace-returnNewDocument>`, the replacement document.
-      
+Returns the original document by default. Returns the updated document
+if :ref:`returnDocument <findOneAndReplace-returnDocument>` is set to
+``after`` or :ref:`returnNewDocument
+<findOneAndReplace-returnNewDocument>` is set to ``true``.
+
 Behavior
 --------
 
@@ -189,14 +174,14 @@ Document Match
 
 :method:`db.collection.findOneAndReplace()` replaces the first matching 
 document in the collection that matches the ``filter``. 
-The ``sort`` parameter can be used to influence which document is modified.
+The ``sort`` field can be used to influence which document is modified.
 
 Projection
 ~~~~~~~~~~
 
 .. include:: /includes/extracts/projection-language-consistency-admonition.rst
 
-The ``projection`` parameter takes a document in the following form:
+The ``projection`` field takes a document in the following form:
 
 .. code-block:: javascript
 
@@ -451,17 +436,17 @@ If the operation exceeds the time limit, it returns:
 Replace Document with Upsert
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following operation uses the :ref:`upsert <findOneAndReplace-upsert>` field to insert the
-replacement document if no document matches the :ref:`filter
-<findOneAndReplace-filter>`:
+The following operation uses the :ref:`upsert
+<findOneAndReplace-upsert>` field to insert the replacement document if
+no document matches the :ref:`filter <findOneAndReplace-filter>`:
 
 .. code-block:: javascript
 
    try {
       db.scores.findOneAndReplace( 
          { "team" : "Fortified Lobsters" },
          { "_id" : 6019, "team" : "Fortified Lobsters" , "score" : 32000},
-         { upsert : true, returnNewDocument: true }
+         { upsert : true, returnDocument: "after" }
       );
    } catch (e){
       print(e);
@@ -477,8 +462,8 @@ The operation returns the following:
       "score" : 32000
    }
 
-If ``returnNewDocument`` was false, the operation would return ``null`` as 
-there is no original document to return.
+If ``returnDocument: "before"`` was set, the operation would return
+``null`` because there is no original document to return.
 
 Specify Collation
 ~~~~~~~~~~~~~~~~~