DOCS-505 edits for consistency and style

Author: Sam Kleinman

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

@@ -7,32 +7,33 @@ db.collection.update()
 .. method:: db.collection.update(query, update, [options])
 
    .. versionchanged:: 2.2 
-      Added new interface to take an ``options`` :term:`document` as a
-      parameter to specify the ``multi`` and the ``upsert`` options.
+      The :program:`mongo` shell adds an updated interface that
+      accepts an parameters in more clear :term:`document` form to
+      specify ``multi`` and ``upsert`` options.
 
-   The :method:`db.collection.update()` method provides the ability to
-   modify a document in a collection. 
-   
-   The default behavior of 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.
+   The :method:`update() <db.collection.update()>` method provides the ability to
+   modify an existing document in a collection.
 
+   By default the :method:`update() <db.collection.update()>` method updates a
+   single document. If you specify a ``multi`` update, the
+   :method:`update() <db.collection.update()>` method will update all
+   documents in the collection that match the query criteria. If you
+   specify ``upsert``, the :method:`update() <db.collection.update()>`
+   method will insert the document if no document matches the query
+   criteria, and preform a conventional update otherwise. The
+   operation has the following form: 
 
-   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
-   ``multi`` parameters to specify the ``multi`` and the ``upsert``
-   options:
-   
    .. code-block:: javascript
 
-      db.collection.update(query, update, [upsert,] [multi])
-   
-   The :method:`db.collection.update()` method takes the following
+      db.collection.update(query, update, <upsert,> <multi>)
+
+   Before version 2.0, in the :program:`mongo` shell, ``upsert`` and
+   ``multi`` were positional boolean options. Since version 2.2, the
+   :method:`update() <db.collection.update()>` method can *also*take an
+   ``options`` :term:`document` as a parameter to specify the
+   ``multi`` and the ``upsert`` options
+      
+   The :method:`update() <db.collection.update()>` method takes the following
    parameters:
 
    :param document query:
@@ -53,66 +54,67 @@ db.collection.update()
           - the ``update`` parameter must contain only :ref:`update
             operators <update-operators>` expressions.
 
-          - the :method:`db.collection.update()` method updates only
+          - the :method:`update() <db.collection.update()>` method updates only
             the corresponding fields in the document.
 
           **If** the ``update`` parameter consists only of ``field:
           value`` expressions, then:
 
-          - the :method:`db.collection.update()` method updates the
+          - the :method:`update() <db.collection.update()>` method updates the
             document to contain only the :term:`_id` field and the
             fields in the ``updates`` parameter.
 
-          - the :method:`db.collection.update()` method updates cannot
+          - the :method:`update() <db.collection.update()>` method updates cannot
             update multiple documents.
 
-   :param document options:
+   :param document options: Optional.
 
-          Optional. A :term:`document` that specifies whether to
+          A :term:`document` that specifies whether to
           perform an :term:`upsert` and/or a multiple update. You can
           use the ``options`` parameter instead of the individual
           ``upsert`` and ``multi`` parameters.
 
-   :param boolean upsert:
+   :param boolean upsert: Optional.
 
-          Optional. A boolean that specifies whether to perform
+          A boolean that specifies whether to perform
           an :term:`upsert`.
 
-          When not specified, the default value is ``false``. When
-          ``true``, the :method:`db.collection.update()` method will
+          The default value is ``false``. When
+          ``true``, the :method:`update() <db.collection.update()>` method will
           update an existing document that matches the ``query``
           selection criteria **or** if no document matches the
           criteria, insert a new document with the fields and values of
-          the ``query`` and ``update``.
+          the ``query`` and ``update`` arguments.
 
-          In version 2.2, you can use the ``options``
-          parameter instead of the ``upsert`` parameter.
+          In version 2.2 of the :program:`mongo` shell, you may also
+          specify ``upsert`` in the ``options`` parameter.
 
           .. note::
 
              An upsert operation affects only *one* document, and
              cannot update multiple documents.
 
-   :param boolean multi: 
+   :param boolean multi: Optional.
 
-          Optional. A boolean that specifies whether to update multiple
-          documents that meet the ``query`` criteria.
+          A boolean that specifies whether to update multiple
+          documents that meet the query criteria.
 
           When not specified, the default value is ``false`` and the
-          :method:`db.collection.update()` method updates a single
+          :method:`update() <db.collection.update()>` method updates a single
           document that meet the ``query`` criteria.
 
-          When ``true``, the :method:`db.collection.update()` method
+          When ``true``, the :method:`update() <db.collection.update()>` method
           updates all documents that meet the ``query`` criteria.
 
-          In version 2.2, you can use the ``options``
-          parameter instead of the ``multi`` parameter.
+          In version 2.2 of the :program:`mongo` shell, you may also
+          specify ``multi`` in the ``options`` parameter.
 
    Consider the following examples of the :method:`update()
-   <db.collection.update()>` method: 
+   <db.collection.update()>` method. These examples all use the 2.2
+   option to specify options in document form. 
 
    - To update specific fields in a single document, you can call the
-     :method:`db.collection.update()` method with the ``update``
+     :method:`update() <db.collection.update()>` method with the ``update``
      parameter consisting of :ref:`update operators <update-operators>`
      expressions, as in the following:
 
@@ -121,52 +123,52 @@ db.collection.update()
         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
+     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 all the fields in a single document with the fields in
+     the ``update`` parameter, call the :method:`update()
+     <db.collection.update()>` method with an ``update`` parameter
+     that consists of ``key: value`` expressions, as in the following:
 
      .. code-block:: javascript
 
         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
+     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, call the
+     :method:`update() <db.collection.update()>` method and specify the
+     ``multi`` option in the ``options`` argument, as in the following:
 
      .. code-block:: javascript
 
         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
+     This operation will update **all** documents in the ``products``
+     collection that match 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``
+     You can perform the same operation by calling the
+     :method:`update() <db.collection.update()>` method with the ``multi``
      parameter:
 
      .. code-block:: javascript
 
         db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, 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:
+     document matches the query criteria, you can call the
+     :method:`update() <db.collection.update()>` and specify the
+     ``upsert`` option in the the ``options`` argument, as in the
+     following:
 
      .. code-block:: javascript
 
@@ -175,7 +177,7 @@ db.collection.update()
      This query will either:
 
      - update a single document in the ``products`` collection that
-       matches the ``query`` criteria, setting the value of the field
+       matches the query criteria, setting the value of the field
        ``x`` to ``25`` and the value of the field ``y`` to ``50``, *or*
 
      - if no matching document exists, insert a document in the
@@ -184,9 +186,9 @@ db.collection.update()
        set to ``50``.
 
      You can also perform the same update by calling the
-     :method:`db.collection.update()` method with the ``upsert``
+     :method:`update() <db.collection.update()>` method with the ``upsert``
      parameter:
 
      .. code-block:: javascript
 
-        db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true )
+        db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } )