DOCS-4968: findAndModify return document

source/includes/fact-findandmodify-return.rst

@@ -0,0 +1,5 @@
+- the original (i.e. pre-modification) document if ``new`` is false, or
+
+- the modified or inserted document if ``new: true``, or
+
+- ``null`` if ``upsert`` is false and the query matches no documents during ``update`` or ``remove``.

source/reference/command/findAndModify.txt

@@ -55,40 +55,12 @@ The return document contains the following fields:
   - The ``upserted`` field **only** appears if the ``update`` with the
     ``upsert: true`` operation results in an insertion.
 
-- The ``value`` field that returns either:
+- The ``value`` field that returns one of:
 
-  - the original (i.e. pre-modification) document if ``new`` is
-    false, or
-
-  - the modified or inserted document if ``new: true``.
+  .. include:: /includes/fact-findandmodify-return.rst
 
 - The ``ok`` field that returns the status of the command.
 
-.. note::
-
-   If the :dbcommand:`findAndModify` finds no matching document,
-   then:
-
-   - for ``update`` or ``remove`` operations, ``lastErrorObject`` does
-     not appear in the return document and the ``value`` field holds a
-     ``null``.
-
-     .. code-block:: javascript
-
-        { "value" : null, "ok" : 1 }
-
-   - 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 ``{}``.
-
-   - 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``.
-
 Behavior
 --------
 
@@ -290,30 +262,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,9 @@ 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:
 
-.. 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/fact-findandmodify-return.rst
 
 Behavior
 --------
@@ -181,11 +165,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

@@ -453,6 +453,14 @@ The minimum 3.0-compatible driver versions are:
 General Compatibility Changes
 -----------------------------
 
+``findAndModify`` Return Document
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 3.0 simplifies the behavior of the :dbcommand:`findAndModify` command.
+Now the ``value`` field in the return document is always ``null`` if ``upsert``
+is false and the query matched no documents during an ``update`` or
+``remove`` operation.
+
 ``upsert:true`` with a Dotted ``_id`` Query
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~