DOCS-4968: findAndModify return document

source/includes/apiargs-dbcommand-findAndModify-lastErrorObject.yaml

@@ -0,0 +1,19 @@
+arg_name: field
+name: updatedExisting
+description: |
+  Contains ``true`` if an ``update`` operation modified an existing document.
+interface: command
+operation: findAndModify
+optional: false
+type: boolean
+---
+arg_name: field
+name: upserted
+description: |
+  Contains the :ref:`objectid` of the inserted document if an ``update``
+  operation with ``upsert: true`` resulted in a new document.
+interface: command
+operation: findAndModify
+optional: false
+type: document
+...

source/includes/apiargs-dbcommand-findAndModify-return.yaml

@@ -0,0 +1,30 @@
+arg_name: field
+description: |
+  Contains the command's returned value. See :ref:`findandmodify-value-field`
+  for details.
+interface: command
+name: value
+operation: findAndModify
+optional: false
+type: document
+---
+arg_name: field
+description: |
+  Contains information about updated documents. See
+  :ref:`findandmodify-lastErrorObject` for details.
+interface: command
+name: lastErrorObject
+operation: findAndModify
+optional: false
+type: document
+---
+arg_name: field
+description: |
+  Contains the command's execution status. ``1`` on success, or ``0`` if an
+  error occurred.
+interface: command
+name: ok
+operation: findAndModify
+optional: false
+type: number
+...

source/includes/extracts-fact-findandmodify-return.yaml

@@ -0,0 +1,34 @@
+ref: _fact-findandmodify-return
+content: |
+  If the ``new`` parameter is not set or is ``false``:
+
+  - the pre-modification document if the query matcches a document,
+
+  - otherwise, ``null``.
+
+  If ``new`` is ``true``:
+
+  - the modified document if the query returns a match,
+
+  - the inserted document if ``upsert: true`` and no document matches the query,
+
+  - otherwise, ``null``.
+
+  Prior to MongoDB 3.0, if ``new`` is not set or is ``false``, ``upsert: true``,
+  and there is a ``sort`` term, then {{op}} would yield an empty document
+  ``{}`` instead of ``null``.
+---
+ref: fact-findandmodify-command-return
+inherit:
+  file: extracts-fact-findandmodify-return.yaml
+  ref: _fact-findandmodify-return
+replacement:
+  op: :dbcommand:`findAndModify`
+---
+ref: fact-findandmodify-method-return
+inherit:
+  file: extracts-fact-findandmodify-return.yaml
+  ref: _fact-findandmodify-return
+replacement:
+  op: :method:`db.collection.findAndModify()`
+...

source/reference/command/findAndModify.txt

@@ -45,49 +45,25 @@ Output
 
 The return document contains the following fields:
 
-- The ``lastErrorObject`` field that returns the details of the
-  command:
+.. include:: /includes/apiargs/dbcommand-findAndModify-return.rst
 
-  - The ``updatedExisting`` field **only** appears if the command
-    specifies an ``update`` or an ``update`` with ``upsert: true``;
-    i.e. the field does not appear for a ``remove``.
+.. _findandmodify-lastErrorObject:
 
-  - The ``upserted`` field **only** appears if the ``update`` with the
-    ``upsert: true`` operation results in an insertion.
-
-- The ``value`` field that returns either:
-
-  - the original (i.e. pre-modification) document if ``new`` is
-    false, or
-
-  - the modified or inserted document if ``new: true``.
-
-- The ``ok`` field that returns the status of the command.
-
-.. note::
+``lastErrorObject``
+~~~~~~~~~~~~~~~~~~~
 
-   If the :dbcommand:`findAndModify` finds no matching document,
-   then:
+The ``lastErrorObject`` embedded document contains the following fields:
 
-   - for ``update`` or ``remove`` operations, ``lastErrorObject`` does
-     not appear in the return document and the ``value`` field holds a
-     ``null``.
+.. include:: /includes/apiargs/dbcommand-findAndModify-lastErrorObject.rst
 
-     .. code-block:: javascript
+.. _findandmodify-value-field:
 
-        { "value" : null, "ok" : 1 }
+``value``
+~~~~~~~~~
 
-   - for ``update`` with ``upsert: true`` operation that results in an
-     insertion, if the command also specifies ``new`` is ``false``
-     **and** specifies a ``sort``, the return document has a
-     ``lastErrorObject``, ``value``, and ``ok`` fields, but the
-     ``value`` field holds an empty document ``{}``.
+The ``value`` embedded document contains the following:
 
-   - for ``update`` with ``upsert: true`` operation that results in an
-     insertion, if the command also specifies ``new`` is ``false`` but
-     does **not** specify a ``sort``, the return document has a
-     ``lastErrorObject``, ``value``, and ``ok`` fields, but the
-     ``value`` field holds a ``null``.
+.. include:: /includes/extracts/fact-findandmodify-command-return.rst
 
 Behavior
 --------
@@ -290,30 +266,7 @@ and returns a document with the following fields:
   command, including the field ``upserted`` that contains the
   ``ObjectId`` of the newly inserted document, and
 
-- The ``value`` field that contains an empty document ``{}`` as the
-  original document because the command included the ``sort`` option:
-
-.. code-block:: sh
-
-   {
-     "lastErrorObject" : {
-        "connectionId" : 1,
-        "updatedExisting" : false,
-        "upserted" : ObjectId("54f62c08c85d4472eadea26e"),
-        "n" : 1,
-        "syncMillis" : 0,
-        "writtenTo" : null,
-        "err" : null,
-        "ok" : 1
-     },
-     "value" : {
-
-     },
-     "ok" : 1
-   }
-
-If the command did **not** include the ``sort`` option, the ``value`` field
-would contain ``null``:
+- The ``value`` field containing ``null``.
 
 .. code-block:: sh
 

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

@@ -45,25 +45,10 @@ Definition
 Return Data
 -----------
 
-The :method:`~db.collection.findAndModify()` method returns either:
-the pre-modification document or, if ``new: true`` is set, the
-modified document.
+The :method:`~db.collection.findAndModify()` method returns one of the
+following:
 
-.. note::
-
-   - If the query finds no document for ``update`` or ``remove``
-     operations, :method:`~db.collection.findAndModify()` returns
-     ``null``.
-
-   - If the query finds no document for an ``update`` with an
-     ``upsert`` operation, :method:`~db.collection.findAndModify()`
-     creates a new document. If ``new`` is ``false``, **and** the
-     ``sort`` option is **NOT** specified, the method returns ``null``.
-
-   - If the query finds no document for an ``update`` with an
-     ``upsert`` operation, :method:`~db.collection.findAndModify()`
-     creates a new document. If ``new`` is ``false``, **and** a
-     ``sort`` option, the method returns an empty document ``{}``.
+.. include:: /includes/extracts/fact-findandmodify-method-return.rst
 
 Behavior
 --------
@@ -181,11 +166,7 @@ This method performs the following actions:
    the method.
 
    If no document matched the ``query`` condition, the method
-   returns ``null``:
-
-   .. code-block:: javascript
-
-      null
+   returns ``null``.
 
 Upsert
 ~~~~~~

source/release-notes/3.0-compatibility.txt

@@ -464,6 +464,17 @@ The minimum 3.0-compatible driver versions are:
 General Compatibility Changes
 -----------------------------
 
+``findAndModify`` Return Document
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In MongoDB 3.0, the return document of the :dbcommand:`findAndModify` command
+has changed when executing ``update`` operatons where the ``query``
+matches no document, ``upsert: true``, and ``new: false``.
+
+Now the return document's ``value`` field will always contain ``null`` in this
+case. Previously, it would instead contain an empty document ``{}`` if the
+arguments included a ``sort`` term.
+
 ``upsert:true`` with a Dotted ``_id`` Query
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~