DOCS-505 v2.2 has improved update() api

Author: kay-kim

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

@@ -14,13 +14,14 @@ db.collection.update()
    modify a document in a collection. 
 
    The default behavior of the :method:`db.collection.update()` method
-   is to update a single document. You can specify the ``multi`` option to
-   update multiple documents that meet the ``query`` criteria.
-   Additionally, you can specify the ``upsert`` option to have the
-   :method:`db.collection.update()` method insert a document into the
-   collection if no document meets the ``query`` criteria.
- 
-   Starting in version 2.2, the :method:`db.collection.update()` method
+   is to update a single document. However, you have the option to
+   perform a ``multi`` update as well as an ``upsert`` update. A
+   ``multi`` update updates multiple documents that meet the query
+   criteria. An :term:`upsert` update inserts a document if no document
+   in the collection matches the ``query`` criteria.
+   
+
+   In version 2.2, the :method:`db.collection.update()` method
    can take an ``options`` :term:`document` as a parameter to specify
    the ``multi`` and the ``upsert`` options. However, the
    :method:`db.collection.update()` still supports the ``upsert`` and
@@ -84,7 +85,7 @@ db.collection.update()
           criteria, insert a new document with the fields and values of
           the ``query`` and ``update``.
 
-          Starting in version 2.2, you can use the ``options``
+          In version 2.2, you can use the ``options``
           parameter instead of the ``upsert`` parameter.
 
           .. note::
@@ -104,85 +105,88 @@ db.collection.update()
           When ``true``, the :method:`db.collection.update()` method
           updates all documents that meet the ``query`` criteria.
 
-          Starting in version 2.2, you can use the ``options``
+          In version 2.2, you can use the ``options``
           parameter instead of the ``multi`` parameter.
 
-Examples
-~~~~~~~~
+   Consider the following examples of the :method:`update()
+   <db.collection.update()>` method: 
 
-- To update specific fields in a single document, you can call the
-  :method:`db.collection.update()` method with the ``update`` parameter
-  consisting of :ref:`update operators <update-operators>` expressions, 
-  as in the following:
+   - To update specific fields in a single document, you can call the
+     :method:`db.collection.update()` method with the ``update``
+     parameter consisting of :ref:`update operators <update-operators>`
+     expressions, as in the following:
 
-  .. code-block:: javascript
+     .. code-block:: javascript
 
-     db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } )
+        db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } )
 
-  This query will update in the ``products`` collection a single
-  document that matches the ``query`` criteria and set the value of the
-  field ``x`` to ``6`` and increment the value of the field ``y`` by
-  ``5``. All other fields of the modified document will remain the same.
+     This query will update in the ``products`` collection a single
+     document that matches the ``query`` criteria and set the value of
+     the field ``x`` to ``6`` and increment the value of the field
+     ``y`` by ``5``. All other fields of the modified document will
+     remain the same.
 
-- To replace completely all the fields in a single document with those
-  in the ``update`` parameter, you can call the
-  :method:`db.collection.update()` method with the ``update`` parameter
-  consisting of ``key:value`` expressions, as in the following:
+   - To replace completely all the fields in a single document with
+     those in the ``update`` parameter, you can call the
+     :method:`db.collection.update()` method with the ``update``
+     parameter consisting of ``key:value`` expressions, as in the
+     following:
 
-  .. code-block:: javascript
+     .. code-block:: javascript
 
-     db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } )
+        db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } )
 
-  This query will update in the ``products`` collection a single
-  document that matches the ``query`` criteria and set the value of the
-  field ``x`` to ``6`` and set the value of the field ``y`` to ``15``.
-  All other fields of the modified document will be **removed** other
-  than the :term:`_id` field.
+     This query will update in the ``products`` collection a single
+     document that matches the ``query`` criteria and set the value of
+     the field ``x`` to ``6`` and set the value of the field ``y`` to
+     ``15``. All other fields of the modified document will be
+     **removed** other than the :term:`_id` field.
 
-- To update multiple documents, you can call the
-  :method:`db.collection.update()` method with the ``options``
-  parameter specifying the ``multi`` option, as in the following:
+   - To update multiple documents, you can call the
+     :method:`db.collection.update()` method with the ``options``
+     parameter specifying the ``multi`` option, as in the following:
 
-  .. code-block:: javascript
+     .. code-block:: javascript
 
-     db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } )
+        db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } )
 
-  This query will update **all** documents in the ``products``
-  collection that matches the ``query`` criteria, setting the value of
-  the field ``x`` to ``6`` and the value of the field ``y`` to ``15``.
-  All other fields in the updated documents remain unchanged.
+     This query will update **all** documents in the ``products``
+     collection that matches the ``query`` criteria, setting the value
+     of the field ``x`` to ``6`` and the value of the field ``y`` to
+     ``15``. All other fields in the updated documents remain unchanged.
 
-  You can also perform the same update by calling the
-  :method:`db.collection.update()` method with the ``multi`` parameter:
-  
-  .. code-block:: javascript
+     You can also perform the same update by calling the
+     :method:`db.collection.update()` method with the ``multi``
+     parameter:
 
-     db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true )
+     .. code-block:: javascript
 
-- To update a single document or to insert a new document if no
-  document matches the ``query`` criteria, you can call the
-  :method:`db.collection.update()` method with the ``options``
-  parameter specifying the ``upsert`` option, as in the following:
+        db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true )
 
-  .. code-block:: javascript
-                 
-     db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } )
+   - To update a single document or to insert a new document if no
+     document matches the ``query`` criteria, you can call the
+     :method:`db.collection.update()` method with the ``options``
+     parameter specifying the ``upsert`` option, as in the following:
 
-  This query will either:
+     .. code-block:: javascript
+                 
+        db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } )
 
-  - update a single document in the ``products`` collection that
-    matches the ``query`` criteria, setting the value of the field
-    ``x`` to ``25`` and the value of the field ``y`` to ``50``, *or*
+     This query will either:
 
-  - if no matching document exists, insert a document in the
-    ``products`` collection, with the field ``item`` set to ``magazine``,
-    the field ``x`` set to ``25``, and the field ``y`` set to ``50``.
+     - update a single document in the ``products`` collection that
+       matches the ``query`` criteria, setting the value of the field
+       ``x`` to ``25`` and the value of the field ``y`` to ``50``, *or*
 
-  You can also perform the same update by calling the
-  :method:`db.collection.update()` method with the ``upsert`` parameter:
+     - if no matching document exists, insert a document in the
+       ``products`` collection, with the field ``item`` set to
+       ``magazine``, the field ``x`` set to ``25``, and the field ``y``
+       set to ``50``.
 
-  .. code-block:: javascript
+     You can also perform the same update by calling the
+     :method:`db.collection.update()` method with the ``upsert``
+     parameter:
 
-     db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true )
+     .. code-block:: javascript
 
-  
+        db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true )