Find and Modify Review Changes

source/reference/command/findAndModify.txt

@@ -13,11 +13,10 @@ Definition
 
 .. dbcommand:: findAndModify
 
-   The :dbcommand:`findAndModify` command atomically modifies and
-   returns a single document. By default, the returned document does
-   not include the modifications made on the update. To return the
-   document with the modifications made on the update, use the ``new``
-   option.
+   The :dbcommand:`findAndModify` command modifies and returns a single
+   document. By default, the returned document does not include the
+   modifications made on the update. To return the document with the
+   modifications made on the update, use the ``new`` option.
 
    The command has the following syntax:
 
@@ -153,6 +152,41 @@ will block other operations until it has completed; however,
 typically the write lock is short lived and equivalent to other
 similar :method:`~db.collection.update()` operations.
 
+Differences with ``update`` Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both :dbcommand:`findAndModify` and :method:`~db.collection.update()`
+atomically update a single document. See
+:doc:`/tutorial/isolate-sequence-of-operations` for more details about
+interactions and order of operations.
+
+The :dbcommand:`findAndModify` command and :method:`~db.collection.update()` method operate
+differently:
+
+- By default, both operations modify a single document. However, the
+  :method:`~db.collection.update()` method with its ``multi`` option can
+  modify more than one document.
+
+- If multiple documents match the update criteria, for
+  :dbcommand:`findAndModify`, you can specify a ``sort`` to provide some
+  measure of control on which document to update. 
+
+  With the default behavior of the :method:`~db.collection.update()`
+  method, you cannot specify which single document to update when multiple documents match.
+
+- By default, the returned document from the :dbcommand:`findAndModify`
+  command is an object that contains the pre-modified version of the
+  document, as well as the status of the operation. To return the updated
+  document in a return object, use the ``new`` option.
+
+  The :method:`~db.collection.update()` method returns a
+  :method:`WriteResult` object that contains the status of the operation.
+  To return the updated document, use the :method:`~db.collection.find()`
+  method. However, other updates may have modified the document between
+  your update and the document retrieval. Also, if the update modified
+  only a single document but multiple documents matched, you will need to
+  use additional logic to identify the updated document.
+
 Examples
 --------
 

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

@@ -123,6 +123,41 @@ all operations against the shard cluster for the *sharded* collections.
 :dbcommand:`findAndModify` operations issued against :program:`mongos`
 instances for *non-sharded* collections function normally.
 
+Differences with ``update`` Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both :method:`~db.collection.findAndModify()` and :method:`~db.collection.update()`
+atomically update a single document. See
+:doc:`/tutorial/isolate-sequence-of-operations` for more details about
+interactions and order of operations of these methods.
+
+The :method:`~db.collection.findAndModify()` and
+:method:`~db.collection.update()` methods operate differently:
+
+- By default, both operations modify a single document. However, the
+  :method:`~db.collection.update()` method with its ``multi`` option can
+  modify more than one document.
+
+- If multiple documents match the update criteria, for
+  :method:`~db.collection.findAndModify()`, you can specify a ``sort`` to provide some
+  measure of control on which document to update. 
+
+  With the default behavior of the :method:`~db.collection.update()`
+  method, you cannot specify which single document to update when multiple documents match.
+
+- By default, the returned document from the
+  :method:`~db.collection.findAndModify()` command is an object that
+  contains the pre-modified version of the document. To return the updated
+  document in a return object, use the ``new`` option.
+
+  The :method:`~db.collection.update()` method returns a
+  :method:`WriteResult` object that contains the status of the operation.
+  To return the updated document, use the :method:`~db.collection.find()`
+  method. However, other updates may have modified the document between
+  your update and the document retrieval. Also, if the update modified
+  only a single document but multiple documents matched, you will need to
+  use additional logic to identify the updated document.
+
 Examples
 --------
 

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

@@ -193,6 +193,8 @@ Sharded Collections
 
 .. include:: /includes/fact-single-modification-in-sharded-collections.rst
 
+.. seealso:: :method:`~db.collection.findAndModify()`
+
 Examples
 --------