trivial: wording tweak to findAndModify

Author: kay-kim

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

@@ -1,34 +1,36 @@
 ref: _fact-findandmodify-return
 content: |
-  If the ``new`` parameter is not set or is ``false``:
+  - If the ``new`` parameter is not set or is ``false``:
 
-  - the pre-modification document if the query matcches a document,
+    - the pre-modification document if the query matches a document;
 
-  - otherwise, ``null``.
+    - otherwise, ``null``.
 
-  If ``new`` is ``true``:
+  - If ``new`` is ``true``:
 
-  - the modified document if the query returns a match,
+    - the modified document if the query returns a match;
 
-  - the inserted document if ``upsert: true`` and no document matches the query,
+    - the inserted document if ``upsert: true`` and no document matches the query;
 
-  - otherwise, ``null``.
+    - 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``.
+  .. versionchanged:: 3.0
+
+     In previous versions, if for the update, ``sort`` is specified,
+     and ``upsert: true``, and the ``new`` option is not set or ``new:
+     false``, {{op}} instead of ``null``.
 ---
 ref: fact-findandmodify-command-return
 inherit:
   file: extracts-fact-findandmodify-return.yaml
   ref: _fact-findandmodify-return
 replacement:
-  op: :dbcommand:`findAndModify`
+  op: ":dbcommand:`findAndModify` returns an empty document ``{}`` in the  ``value`` field"
 ---
 ref: fact-findandmodify-method-return
 inherit:
   file: extracts-fact-findandmodify-return.yaml
   ref: _fact-findandmodify-return
 replacement:
-  op: :method:`db.collection.findAndModify()`
+  op: ":method:`db.collection.findAndModify()` returns an empty document ``{}``"
 ...

source/reference/command/findAndModify.txt

@@ -43,7 +43,8 @@ Definition
 Output
 ------
 
-The return document contains the following fields:
+The :dbcommand:`findAndModify` command returns a document with the
+following fields:
 
 .. include:: /includes/apiargs/dbcommand-findAndModify-return.rst
 
@@ -61,7 +62,12 @@ The ``lastErrorObject`` embedded document contains the following fields:
 ``value``
 ~~~~~~~~~
 
-The ``value`` embedded document contains the following:
+For ``remove`` operations, ``value`` contains the removed document if
+the query matches a document. If the query does not match a document to
+remove, ``value`` contains ``null``.
+
+For ``update`` operations, the ``value`` embedded document contains the
+following:
 
 .. include:: /includes/extracts/fact-findandmodify-command-return.rst
 
@@ -324,8 +330,8 @@ The command returns the newly inserted document in the ``value`` field:
         "_id" : ObjectId("54f62bbfc85d4472eadea26d"),
         "name" : "Pascal",
         "rating" : 25,
-        "state" : "active"
-        "score" : 1,
+        "state" : "active",
+        "score" : 1
      },
      "ok" : 1
    }

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

@@ -45,8 +45,13 @@ Definition
 Return Data
 -----------
 
-The :method:`~db.collection.findAndModify()` method returns one of the
-following:
+For remove operations, if the query matches a document,
+:method:`~db.collection.findAndModify()` returns the removed document.
+If the query does not match a document to remove,
+:method:`~db.collection.findAndModify()` returns ``null``.
+
+For update operations, :method:`~db.collection.findAndModify()` returns
+one of the following:
 
 .. include:: /includes/extracts/fact-findandmodify-method-return.rst
 

source/release-notes/3.0-compatibility.txt

@@ -467,13 +467,17 @@ 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.
+In MongoDB 3.0, when performing an update with
+:dbcommand:`findAndModify` that also specifies ``upsert: true`` *and*
+either the ``new`` option is not set or ``new: false``,
+:dbcommand:`findAndModify` returns ``null`` in the ``value`` field if
+the ``query`` does not match any document, regardless of the ``sort``
+specification.
+
+In previous versions, :dbcommand:`findAndModify` returns an empty
+document ``{}`` in the ``value`` field if a ``sort`` is specified for
+the update, and ``upsert: true``, and the ``new`` option is not set or
+``new: false``.
 
 ``upsert:true`` with a Dotted ``_id`` Query
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~