DOCS-503 positional operator doc

source/reference/operator/positional.txt

@@ -6,7 +6,7 @@
 
 .. operator:: $
 
-   *Syntax*: ``{ "array.$" : value }``
+   *Syntax*: ``{ "<array>.$" : value }``
 
    The positional :operator:`$` operator identifies an element in an
    ``array`` field to update without explicitly specifying the position
@@ -29,9 +29,9 @@
       { "_id" : 2, "grades" : [ 88, 90, 92 ] }
       { "_id" : 3, "grades" : [ 85, 100, 90 ] }
 
-   To update ``80`` to ``82`` in the ``grades`` array field in the
-   first document, you can use the positional :operator:`$` operator if
-   you did not know the position of the element in the array:
+   To update ``80`` to ``82`` in the ``grades`` array in the
+   first document, use the positional :operator:`$` operator if
+   you do not know the position of the element in the array:
 
    .. code-block:: javascript
 
@@ -41,9 +41,10 @@
    placeholder for the **first match** of the update ``query selector``.
 
    The positional :operator:`$` operator facilitates updates to arrays
-   that contain embedded documents. You can access the fields in the
-   embedded documents by applying the dot-notation on the :operator:`$`
-   operator.
+   that contain embedded documents. Use the positional :operator:`$`
+   operator to access the fields in the embedded documents with the
+   :wiki:`dot notation <Dot+Notation+(Reaching+into+Objects)>` on the
+   :operator:`$` operator.
 
    .. code-block:: javascript
 
@@ -58,9 +59,8 @@
                                 { grade: 85, mean: 90, std: 5 },
                                 { grade: 90, mean: 85, std: 3 } ] }
 
-   To update the ``std`` value of the embedded document with the
-   ``grade`` of ``85``, you can use the positional :operator:`$`
-   operator:
+   Use the positional :operator:`$` operator to update the value of the
+   ``std`` field in the embedded document with the ``grade`` of ``85``:
 
    .. code-block:: javascript
 
@@ -69,14 +69,15 @@
    Consider the following behaviors when using the positional
    :operator:`$` operator:
 
-   - The positional :operator:`$` operator should not be used with an
+   - Do not use the positional :operator:`$` operator with an
      :term:`upsert` since an insert will use the ``$`` as a field name
      in the inserted document.
 
-   - When used with the :operator:`$unset` operator, the positional
-     :operator:`$` operator does not remove the matching element from
-     the array but rather set it to ``null``.
+   - Be aware that using the positional :operator:`$` operator with the
+     :operator:`$unset` operator does not remove the matching element
+     from the array but rather set it to ``null``.
 
    .. seealso::
 
-      :method:`update() <db.collection.update()>`, :operator:`$set`.
+      :method:`update() <db.collection.update()>`, :operator:`$set` and
+      :operator:`$unset`