DOCS-799 incorporate scotts comments

Author: kay-kim

source/reference/meta-query-operators.txt

@@ -11,27 +11,24 @@ Introduction
 
 In addition to the :doc:`MongoDB Query Operators
 </reference/operators>`, there are a number of "meta" operators that
-you may use to modify the output or behavior of a
-query. Specify these modifiers to a :method:`db.collection.find()` query, in the
-following forms (for the :program:`mongo` shell):
+you may use to modify the output or behavior of a query. On the server,
+MongoDB treats the query and the options as a single object. The
+:program:`mongo` shell may provide :ref:`cursor methods
+<js-query-cursor-methods>` for these options. When possible, use these
+methods; otherwise, you can add these options using either of the
+following syntax:
 
 .. code-block:: javascript
 
-   db.collection.find( { <QUERY> } )._addSpecial( <MODIFIER> )
-   db.collection.find( { $query: { <QUERY> }, <MODIFIER> } )
- 
-Here, the query specified by ``<QUERY>`` runs on the collection named
-``collection`` with the operation specified by the ``<MODIFIER>``. The
-results are then processed by a modifier expression selected from the
-following list. MongoDB treats the query and the
-modifiers as a single object, with the :operator:`$query` and the meta
-operators included in a single document.
+   db.collection.find( { <query> } )._addSpecial( <option> )
+   db.collection.find( { $query: { <query> }, <option> } )
 
 Modifiers
 ---------
 
-Many of the operators have corresponding :doc:`methods
-in the shell </reference/javascript>`. 
+Many of these operators have corresponding :ref:`methods in the shell
+<js-query-cursor-methods>`. These methods provide a straightforward and
+user-friendly interface and are the preferred way to add these options.
 
 .. include:: operator/returnKey.txt
    :start-after: mongodb

source/reference/operator/comment.txt

@@ -14,5 +14,5 @@ $comment
 
    .. code-block:: javascript
 
-      db.collection.find( { <QUERY> } )._addSpecial( "$comment", <comment to add> )
-      db.collection.find( { $query: { <QUERY> }, $comment: <comment to add> } )
+      db.collection.find( { <query> } )._addSpecial( "$comment", <comment to add> )
+      db.collection.find( { $query: { <query> }, $comment: <comment to add> } )

source/reference/operator/explain.txt

@@ -11,19 +11,16 @@ $explain
    the process and indexes used to return the query. This may provide
    useful insight when attempting to optimize a query.
 
-   Retrieve the query plan by adding the :operator:`$explain` operator
-   to a :method:`find() <db.collection.find()>` query, as in the
-   following examples:
+   The :program:`mongo` shell provides the :method:`cursor.explain()`
+   method:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial( "$explain", 1 )
-       db.collection.find( { $query: {}, $explain: 1 } )
+      db.collection.find().explain()
 
-   The JavaScript function :method:`cursor.explain()` provides equivalent
-   functionality in the :program:`mongo` shell. See the following
-   example, which is equivalent to the above:
+   You can also specify the option in either of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find().explain()
+      db.collection.find()._addSpecial( "$explain", 1 )
+      db.collection.find( { $query: {}, $explain: 1 } )

source/reference/operator/hint.txt

@@ -6,24 +6,23 @@ $hint
 
 .. operator:: $hint
 
-   Use the :operator:`$hint` operator to force the query optimizer to
-   use a specific index to fulfill the query.  Use :operator:`$hint`
-   for testing query performance and indexing strategies. Consider
-   the following operations:
+   The :operator:`$hint` operator forces the query optimizer to use a
+   specific index to fulfill the query. You can use :operator:`$hint`
+   for testing query performance and indexing strategies. The
+   :program:`mongo` shell provides the :method:`cursor.hint()` method:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial( "$hint", { _id : 1 } )
-       db.collection.find( { $query: {}, $hint: { _id : 1 } } )
+      db.collection.find().hint( { age: 1 } )
 
-   These are equivalent to the following :method:`cursor.hint()` method that
-   may be more familiar to you:
+   This operation returns all documents in the collection named
+   ``collection`` using the index on the ``age`` field. Use this
+   operator to override MongoDB's default index selection process and
+   pick indexes manually.
 
-   .. code-block:: javascript
+   You can also specify the option in either of the following forms:
 
-      db.collection.find().hint( { _id: 1 } )
+   .. code-block:: javascript
 
-   These operations return all documents in the collection named
-   ``collection`` using the index on the ``_id`` field. Use this
-   operator to override MongoDB's default index selection process and
-   pick indexes manually.
+      db.collection.find()._addSpecial( "$hint", { age : 1 } )
+      db.collection.find( { $query: {}, $hint: { age : 1 } } )

source/reference/operator/max.txt

@@ -8,34 +8,72 @@ $max
 
    Specify a :operator:`$max` value to specify the *exclusive* upper
    bound for a specific index in order to constrain the results of
-   :method:`find() <db.collection.find()>`. Consider the following
-   operations on a collection named ``collection`` that has an index
-   ``{ age: 1 }``:
+   :method:`find() <db.collection.find()>`. The :program:`mongo` shell
+   provides the :method:`cursor.max()` wrapper method:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial( "$max", { age : 100 } )
-       db.collection.find( { $query: {}, $max: { age: 100 } } )
+      db.collection.find( { <query> } ).max( { field1: <max value>, ... fieldN: <max valueN> } )
 
-   These are equivalent to the following :method:`cursor.max()` method that
-   may be more familiar to you:
+   You can also specify the option with either of the two forms:
 
    .. code-block:: javascript
 
-      db.collection.find().max( { age: 100 } )
-      
+      db.collection.find( { <query> } )._addSpecial( "$max", { field1: <max value1>, ... fieldN: <max valueN> } )
+      db.collection.find( { $query: { <query> }, $max: { field1: <max value1>, ... fieldN: <max valueN> } } )
+
+   The :operator:`$max` specifies the upper bound for *all* keys of a
+   specific index *in order*.
+
+   Consider the following operations on a collection named
+   ``collection`` that has an index ``{ age: 1 }``:
+
+   .. code-block:: javascript
+
+      db.collection.find( { <query> } ).max( { age: 100 } )
+
    This operation above limits the query to those documents where the
    field ``age`` is less than ``100`` using the index ``{ age: 1 }``.
-   You can explicitly specify the particular index with the
-   :operator:`$hint`. Otherwise, MongoDB selects the index using the
-   fields in the ``indexbounds``; however, if multiple indexes exist on
-   same fields with different sort orders, the selection of the index
-   may be ambiguous.
+   
+   You can explicitly specify the corresponding index with
+   :method:`cursor.hint()`. Otherwise, MongoDB selects the index using
+   the fields in the ``indexbounds``; however, if multiple indexes
+   exist on same fields with different sort orders, the selection of
+   the index may be ambiguous.
+
+   Consider a collection named ``collection`` that has the following
+   two indexes:
+
+   .. code-block:: javascript
+
+      { age: 1, type: -1 }
+      { age: 1, type: 1 }
 
-   Use operation alone or in conjunction with :operator:`$min`
-   to limit results to a specific range for the same index.
+   Without explicitly using :method:`cursor.hint()`, it is unclear
+   which index the following operation will select:
+
+   .. code-block:: javascript
+
+      db.collection.find().max( { age: 50, type: 'B' } )
+
+   Use operation alone or in conjunction with :operator:`$min` to limit
+   results to a specific range for the *same* index, as in the
+   following example:
+
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20 } ).max( { age: 25 } )
 
    .. note::
 
-      In most cases, you should avoid this operator in favor of
-      :operator:`$lt`.
+      Because :method:`cursor.max()` requires an index on a field, and
+      forces the query to use this index, you may prefer the
+      :operator:`$lt` operator for the query if possible. Consider the
+      following example:
+
+      .. code-block:: javascript
+
+         db.collection.find( { _id: 7 } ).max( { age: 25 } )
+
+      The query will use the index on the ``age`` field, even if the
+      index on ``_id`` may be better.

source/reference/operator/maxScan.txt

@@ -11,8 +11,8 @@ $maxScan
 
    .. code-block:: javascript
 
-      db.collection.find( { <QUERY> } )._addSpecial( "$maxScan" , <number> )
-      db.collection.find( { $query: { <QUERY> }, $maxScan: <number> } )
+      db.collection.find( { <query> } )._addSpecial( "$maxScan" , <number> )
+      db.collection.find( { $query: { <query> }, $maxScan: <number> } )
 
    Use this modifier to prevent potentially long running queries from
    disrupting performance by scanning through too much data.

source/reference/operator/min.txt

@@ -8,34 +8,72 @@ $min
 
    Specify a :operator:`$min` value to specify the *inclusive* lower
    bound for a specific index in order to constrain the results of
-   :method:`find() <db.collection.find()>`. Consider the following
-   operations on a collection named ``collection`` that has an index
-   ``{ age: 1 }``:
+   :method:`find() <db.collection.find()>`. The :program:`mongo` shell
+   provides the :method:`cursor.min()` wrapper method:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial("$min" , { age : 20 } )
-      db.collection.find( { $query: {}, $min: { age: 20 } } )
+      db.collection.find( { <query> } ).min( { field1: <min value>, ... fieldN: <min valueN>} )
 
-   These are equivalent to the following :method:`cursor.min()` method that
-   may be more familiar to you:
+   You can also specify the option with either of the two forms:
+
+   .. code-block:: javascript
+
+      db.collection.find( { <query> } )._addSpecial( "$min", { field1: <min value1>, ... fieldN: <min valueN> } )
+      db.collection.find( { $query: { <query> }, $min: { field1: <min value1>, ... fieldN: <min valueN> } } )
+
+   The :operator:`$min` specifies the lower bound for *all* keys of a
+   specific index *in order*. 
+   
+   Consider the following operations on a collection named
+   ``collection`` that has an index ``{ age: 1 }``:
 
    .. code-block:: javascript
 
       db.collection.find().min( { age: 20 } )
-      
-   These operations limits the query to those documents where the field
-   ``age`` is at least ``20`` using the index ``{ age: 1 }``. You can
-   explicitly specify the particular index with :operator:`$hint`.
-   Otherwise, MongoDB selects the index using the fields in the
-   ``indexbounds``; however, if multiple indexes exist on same fields
-   with different sort orders, the selection of the index may be
-   ambiguous.
-
-   Use operation alone or in conjunction with :operator:`$max` to limit
-   results to a specific range for the same index.
+
+   These operations limit the query to those documents where the field
+   ``age`` is at least ``20`` using the index ``{ age: 1 }``.
+
+   You can explicitly specify the corresponding index with
+   :method:`cursor.hint()`. Otherwise, MongoDB selects the index using
+   the fields in the ``indexbounds``; however, if multiple indexes
+   exist on same fields with different sort orders, the selection of
+   the index may be ambiguous.
+
+   Consider a collection named ``collection`` that has the following
+   two indexes:
+
+   .. code-block:: javascript
+
+      { age: 1, type: -1 }
+      { age: 1, type: 1 }
+
+   Without explicitly using :method:`cursor.hint()`, it is unclear
+   which index the following operation will select:
+
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20, type: 'C' } )
+
+   You can use :operator:`$min` in conjunction with :operator:`$max` to
+   limit results to a specific range for the *same* index, as in the
+   following example:
+   
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20 } ).max( { age: 25 } )
 
    .. note::
 
-      In most cases, you should avoid this operator in favor of
-      :operator:`$gte`.
+      Because :method:`cursor.min()` requires an index on a field, and
+      forces the query to use this index, you may prefer the
+      :operator:`$gte` operator for the query if possible. Consider the
+      following example:
+
+      .. code-block:: javascript
+
+         db.collection.find( { _id: 7 } ).min( { age: 25 } )
+
+      The query will use the index on the ``age`` field, even if the
+      index on ``_id`` may be better.

source/reference/operator/orderby.txt

@@ -7,19 +7,21 @@ $orderby
 .. operator:: $orderby
 
    The :operator:`$orderby` operator sorts the results of a query in
-   ascending or descending order. Consider the following operations:
+   ascending or descending order.
+
+   The :program:`mongo` shell provides the :method:`cursor.sort()`
+   method:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$orderby", { age : -1 } )
-      db.collection.find( { $query: {}, $orderby: { age : -1 } } )
+      db.collection.find().sort( { age: -1 } )
 
-   These are equivalent to the following :method:`cursor.sort()` method that
-   may be more familiar to you:
+   You can also specify the option in either of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find().sort( { age: -1 } )
+      db.collection.find()._addSpecial( "$orderby", { age : -1 } )
+      db.collection.find( { $query: {}, $orderby: { age : -1 } } )
 
    These examples return all documents in the collection named
    ``collection`` sorted by the ``age`` field in descending order.
@@ -29,9 +31,7 @@ $orderby
 
    Unless you have a index for the specified key pattern, use
    :operator:`$orderby` in conjunction with :operator:`$maxScan` and/or
-   :method:`cursor.limit()` to avoid requiring MongoDB to perform a large
-   in-memory sort. :method:`cursor.limit()` increases the speed and reduce
-   the amount of memory required to return this query by way of an
-   optimized algorithm.
-   
-   .. seealso:: :operator:`$query` operator
+   :method:`cursor.limit()` to avoid requiring MongoDB to perform a
+   large in-memory sort. The :method:`cursor.limit()` increases the
+   speed and reduces the amount of memory required to return this query
+   by way of an optimized algorithm.

source/reference/operator/returnKey.txt

@@ -13,5 +13,5 @@ $returnKey
 
    .. code-block:: javascript
 
-      db.collection.find( { <QUERY> } )._addSpecial( "$returnKey", true )
-      db.collection.find( { $query: { <QUERY> }, $returnKey: true } )
+      db.collection.find( { <query> } )._addSpecial( "$returnKey", true )
+      db.collection.find( { $query: { <query> }, $returnKey: true } )

source/reference/operator/showDiskLoc.txt

@@ -6,11 +6,20 @@ $showDiskLoc
 
 .. operator:: $showDiskLoc
 
-   Use the following modifier to display the disk location information
-   as an additional field ``$diskLoc`` in the returned documents. Use
-   one of the following forms:
+   :operator:`$showDiskLoc` option adds a field ``$diskLoc`` to the returned
+   documents. The ``$diskLoc`` field contains the disk location
+   information.
+
+   The :program:`mongo` shell provides the :method:`cursor.showDiskLoc()`
+   method:
+
+   .. code-block:: javascript
+
+      db.collection.find().showDiskLoc()
+
+   You can also specify the option in either of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find( { <QUERY> } )._addSpecial("$showDiskLoc" , true)
-      db.collection.find( { $query: { <QUERY> }, $showDiskLoc: true } )
+      db.collection.find( { <query> } )._addSpecial("$showDiskLoc" , true)
+      db.collection.find( { $query: { <query> }, $showDiskLoc: true } )