DOCS-484: counter edits

Author: Sam Kleinman

source/includes/note-ref-equality.rst

@@ -1,10 +1,18 @@
 .. note::
 
-   To signify ``equal to`` (``=``), MongoDB defaults to the JSON ``{
-   key:value }`` structure. For example, the query:
+   To express ``equal to`` (e.g. ``=``) in the MongoDB query language,
+   use JSON ``{ key:value }`` structure. Consider the following
+   prototype:
 
    .. code-block:: javascript
    
       db.collection.find( { field: value } )
       
-   selects all the documents where the ``field`` equals ``value``.
+   For example: 
+   
+   .. code-block:: javascript
+   
+      db.collection.find( { a: 42 } )
+   
+   This query selects all the documents the where the ``a`` field
+   holds a value of ``42``.

source/reference/operator/all.txt

@@ -6,48 +6,53 @@ $all
 
 .. operator:: $all
 
-   *Syntax*: ``{ field: { $all: [ < value1 > , < value2 > ... ] }``
+   *Syntax*: ``{ field: { $all: [ <value> , <value1> ... ] }``
 
    :operator:`$all` selects the documents where the ``field`` is an
-   array and contains all the ``<values>`` in the array.  
+   array and contains all items (e.g. ``<value>``, ``<value1>``, etc.)
+   in the array.
 
-   For example, you would query:
+   For example:
 
    .. code-block:: javascript
 
-      db.inventory.find( { tags: { $all: [ "appliances", "school" ] } } )
+      db.inventory.find( { tags: { $all: [ "appliances", "school", "book" ] } } )
 
-   to select all documents in ``inventory`` where ``tags`` contains all
-   the elements in the array ``[ "appliances", "school" ]``.  So, in the case of:
+   This query selects all documents in the ``inventory`` collection
+   where the ``tags`` field contains an array with the elements,
+   ``appliances``, ``school``, and ``technology``. 
+
+   Therefore, the above query will match documents in the
+   ``inventory`` collection that have a ``tags`` that hold *either* of
+   the following arrays: 
 
-   - a document with ``tags`` equal to ``[ "school", "book", "bag",
-     "headphone", "appliances" ]`` *and* 
-   - a document with ``tags`` equal to ``[ "appliances",
-     "school" ]``, 
-     
-   the above query will return both documents.
+   .. code-block:: javascript
 
-   Although :operator:`$all` is most meaningful when queried against an array
-   ``field``, you can use :operator:`$all`  to query against a non-array ``field``.
+      [ "school", "book", "bag", "headphone", "appliances" ]
+      [ "appliances", "school", "book" ]
 
-   For example, you could query:
+   :operator:`$all` exists describe and specify arrays in MongoDB
+   queries. you may use :operator:`$all`  to select against a
+   non-array ``field``, as in the following example: 
 
    .. code-block:: javascript
 
       db.inventory.find( { qty: { $all: [ 50 ] } } )
 
-   to select all documents in ``inventory`` where the integer ``qty``
-   equals ``50``; **however** you should, instead, use:
+    **However**, use the following form to express the same query: 
 
    .. code-block:: javascript
 
       db.inventory.find( { qty: 50 } )
-    
+
+   Both queries will select all documents in the ``inventory``
+   collection where the value of the ``qty`` field equals ``50``.
+
    .. note::
 
       In most cases, MongoDB does not treat arrays as sets. This
-      operator provides a notable exception to this general approach.
+      operator provides a notable exception to this approach.
 
    .. seealso:: 
       :method:`find() <db.collection.find()>`, :method:`update()
-      <db.collection.update()>`, :operator:`$set`.
+      <db.collection.update()>`, and :operator:`$set`.

source/reference/operator/and.txt

@@ -10,49 +10,51 @@ $and
 
    *Syntax*: ``{ $and: [ { <expression1> }, { <expression2> } , ... , { <expressionN> } ] }`` 
 
-   :operator:`$and` performs a logical ``AND`` operation on an array of
-   *two or more* ``<expressions>`` and selects the
-   documents that satisfy *all* the ``<expressions>`` in the array.
+   :operator:`$and` performs a logical ``AND`` operation on an array
+   of *two or more* expressions (e.g. ``<expression1>``,
+   ``<expression2>``, etc.) and selects the documents that satisfy
+   *all* the expressions in the array.
 
-   For example, you would query: 
+   Consider the following example: 
 
    .. code-block:: javascript
 
       db.inventory.find({ $and: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } )
 
-   to select all documents in ``inventory`` where:
+   This query will select all documents in the ``inventory``
+   collection where:
 
    - ``price`` equals ``1.99`` **and** 
    - ``qty`` is less than ``20`` **and**
    - ``sale`` is ``true``.
 
    MongoDB provides an implicit ``AND`` operation when specifying a
-   comma separated list of expressions. For example, you can write the
+   comma separated list of expressions. For example, you may write the
    above query as:
 
    .. code-block:: javascript
 
       db.inventory.find( { price: 1.99, qty: { $lt: 20 } , sale: true } )
 
-   
-   However, you need to use the :operator:`$and` operator when you need an
-   ``AND`` operation on the value of a single field.
-   
-   For example, you would query: 
-   
+   For queries that require an ``AND`` operation on the value of a
+   single field, you *must* use the :operator:`$and` operator. For
+   example: 
+
    .. code-block:: javascript
 
       db.inventory.update( { $and: [ { price: { $ne: 1.99 } }, { price: { $exists: true } } ] }, { $set: { qty: 15 } } )
 
-   to update a single document in ``inventory`` where:
-   
-   - ``price`` does not equal ``1.99`` **and** 
-   - ``price`` exists.
+   This :method:`update() <db.collection.update()>` operation will set
+   the value of the ``qty`` field in documents where the value of the
+   ``price`` field: 
+
+   -  does not equal ``1.99`` **and** 
+   -  exists.
 
    .. seealso:: 
 
       :method:`find() <db.collection.find()>`, :method:`update()
       <db.collection.update()>`, :operator:`$ne`, :operator:`$exists`,
       :operator:`$set`.
 
-    
+    

source/reference/operator/gte.txt

@@ -9,28 +9,28 @@ $gte
    *Syntax*: ``{field: {$gte: value} }``
 
    :operator:`$gte` selects the documents where the ``field`` is
-   greater than or equal to (i.e. ``>=``) the specified ``value``.
-
-   For example, you would query:
+   greater than or equal to (i.e. ``>=``) a specified value
+   (e.g. ``value``.) Consider the following example: 
 
    .. code-block:: javascript
 
       db.inventory.find( { qty: { $gte: 20 } } )
 
-   to select all documents in ``inventory`` where ``qty`` is greater than
-   or equal to ``20``.
+   This query would select all documents in ``inventory`` where
+   ``qty`` is greater than or equal to ``20``.
 
-   You may use the :operator:`$lt` operator to select fields from
-   embedded documents. For example, you would query:
+   You may use the :operator:`$gte` operator to select fields from
+   embedded documents, as in the following example:
 
    .. code-block:: javascript
 
       db.inventory.update( { "carrier.fee": { $gte: 2 } }, { $set: { price: 9.99 } } )
 
-   to update a single document in ``inventory`` where the field ``fee``
-   from the embedded document ``carrier`` is greater than ``2``.
+   This :method:`update() <db.collection.update()>` operation will set
+   the value of the ``price`` field where the ``fee`` field in the
+   document embedded in the ``carrier`` field is greater than ``2``.
 
    .. seealso::
 
       :method:`find() <db.collection.find()>`, :method:`update()
-      <db.collection.update()>`, :operator:`$set`.
+      <db.collection.update()>`, :operator:`$set`.

source/reference/operator/in.txt

@@ -9,32 +9,37 @@ $in
    *Syntax*: ``{ field: { $in: [<value1>, <value2>, ... <valueN> ] } }``
 
    :operator:`$in` selects the documents where the ``field`` equals any
-   value in the specified ``array``.
-   
-   For example, you would query: 
+   value in the specified array (e.g. ``<value1>``, <value2>``, etc.)
+   Consider the following example: 
 
    .. code-block:: javascript
 
       db.inventory.find( { qty: { $in: [ 5, 15 ] } } )
 
-   to select all documents in ``inventory`` where ``qty`` is either ``5`` or ``15``.
+   This query will select to select all documents in ``inventory``
+   where ``qty`` is either ``5`` or ``15``.  Although you can express
+   this query using the :operator:`$or` operator, prefer
+   :operator:`$in` in favor of :operator:`$or` when performing
+   equality checks on a single field.
 
-   Although you could write the above query using the :operator:`$or`
-   operator, :operator:`$in` is preferred over :operator:`$or` when
-   performing equality checks for the same.
+   If the field holds an array, then the following expression is true
+   *if* any element specified with the :operator:`$in` expression is
+   in the array.
+
+   .. code-block:: javascript
 
-   If the ``field`` is an array, then ``{ field: { $in: array } }``
-   is true *if* at least one element of the ``field`` is found in the ``array``.
+      { field: { $in: [ array ] } }
 
-   For example, the query:
+   Consider the following example:
 
    .. code-block:: javascript
 
       db.inventory.update( { tags: { $in: ["appliances", "school"] } }, { $set: { sale:true } } )
 
-   will update a single document in ``inventory`` where at least one
-   element of the ``tags`` array matches an element in ``["appliances",
-   "school"]``.
+   This :method:`update() <db.collection.update()>` operation will set
+   the value of ``sale`` in the ``inventory`` collection where at
+   least one element of the ``tags`` array matches an element in the
+   array ``["appliances", "school"]``.
 
    .. seealso::