DOCS-64 edits

Author: Sam Kleinman

source/reference/operator/rename.txt

@@ -6,6 +6,8 @@ $rename
 
 .. operator:: $rename
 
+   .. versionadded:: 1.7.2
+
    *Syntax*: ``{$rename: { <old name1>: <new name1>, <old name2>: <new name2>, ... } }``
 
    The :operator:`$rename` operator updates the name of a field. The
@@ -47,7 +49,7 @@ $rename
 
         db.students.update( { _id: 1 }, { $rename: { "nmae": "name" } } )
 
-     The operation renames the sub-document ``nmae`` to ``name``:
+     This operation renames the sub-document ``nmae`` to ``name``:
 
      .. code-block:: javascript
 
@@ -67,7 +69,7 @@ $rename
 
         db.students.update( { _id: 1 }, { $rename: { "name.first": "name.fname" } } )
 
-     The operation renames the sub-document field ``first`` to ``fname``:
+     This operation renames the sub-document field ``first`` to ``fname``:
 
      .. code-block:: javascript
 
@@ -87,7 +89,7 @@ $rename
 
         db.students.update( { _id: 1 }, { $rename: { "name.last": "contact.lname" } } )
 
-     The operation renames the sub-document field ``last`` to ``lname`` and
+     This operation renames the sub-document field ``last`` to ``lname`` and
      moves it to the sub-document ``contact``:
 
      .. code-block:: javascript
@@ -114,8 +116,8 @@ $rename
 
         db.students.update( { _id: 1 }, { $rename: { 'wife': 'spouse' } } )
 
-     The operation performs no action since the field with the name
-     ``wife`` does not exist.
+     This operation does nothing because there is no field named
+     ``wife``.
 
    - When renaming multiple fields and **all** of the old field names
      refer to non-existing fields, the :operator:`$rename` operator
@@ -127,8 +129,8 @@ $rename
                                                      'vice': 'vp',
                                                      'office': 'term' } } )
 
-     The operation performs no action since fields with the names
-     ``wife``, ``vice``, and ``office`` do not exist.
+     This operation does nothing because there are no fields named 
+     ``wife``, ``vice``, and ``office``.
 
    - When renaming multiple fields and **some** but not all old field
      names refer to non-existing fields, the :operator:`$rename`
@@ -150,7 +152,8 @@ $rename
         db.students.update( { _id: 1 }, { $rename: { 'wife': 'alias', 
                                                      'mobile': 'cell' } } )
 
-     The operation renames the ``mobile`` field to ``cell``. No other
+     This operation renames the ``mobile`` field to ``cell``, and has
+     no other impact
      action occurs.
 
      .. code-block:: javascript
@@ -165,20 +168,21 @@ $rename
 
      .. note:: 
 
-        Before version 2.2, when renaming multiple fields and some but
-        not all old field names refer to non-existing fields:
+        Before version 2.2, when renaming multiple fields and only some (but
+        not all) old field names refer to non-existing fields:
 
         - **if** no field exists with the new field name, the
           :operator:`$rename` operator does nothing.
 
         - **if** fields already exist with the new field names, the
           :operator:`$rename` operator drops these fields.
 
-        Consider the following query that renames both an existing
-        field ``mobile`` and a non-existing field ``wife``. The
-        non-existing field ``wife`` is to be set to ``alias``, a name
-        that already exists.
-     
+        Consider the following operation that renames both the
+        field ``mobile``, which exists, the  field ``wife``, which
+        does not exist. The operation will set the 
+        field named ``wife`` ``alias``, which is the name of an
+        existing field: 
+
         .. code-block:: javascript
 
            db.students.update( { _id: 1 }, { $rename: { 'wife': 'alias', 'mobile': 'cell' } } )
@@ -194,5 +198,3 @@ $rename
              "name" : { "lname" : "washington" },
              "places" : { "d" : "Mt Vernon", "b" : "Colonial Beach" }
            }
-   
-   .. versionadded:: 1.7.2