From c5bc88976735aabb8326e4a75044d651fb2d66be Mon Sep 17 00:00:00 2001
From: kay <kay.kim@10gen.com>
Date: Tue, 4 Dec 2012 13:11:35 -0500
Subject: [PATCH 1/2] DOCS-799 Port mongo query language wiki

---
 source/administration/indexes.txt         |  2 +-
 source/core/read-operations.txt           | 20 +++++++++++--
 source/reference/meta-query-operators.txt | 26 ++++++++++-------
 source/reference/operator/comment.txt     | 13 ++++-----
 source/reference/operator/explain.txt     | 13 ++++++---
 source/reference/operator/hint.txt        | 12 ++++++--
 source/reference/operator/max.txt         | 32 ++++++++++++++-------
 source/reference/operator/maxScan.txt     |  5 ++--
 source/reference/operator/min.txt         | 34 +++++++++++++++--------
 source/reference/operator/orderby.txt     | 19 +++++++------
 source/reference/operator/query.txt       |  9 ++++--
 source/reference/operator/returnKey.txt   |  9 ++++--
 source/reference/operator/showDiskLoc.txt |  8 ++++--
 source/reference/operator/snapshot.txt    | 25 ++++++++---------
 14 files changed, 147 insertions(+), 80 deletions(-)

diff --git a/source/administration/indexes.txt b/source/administration/indexes.txt
index 68298e0ac70..f6b86229c26 100644
--- a/source/administration/indexes.txt
+++ b/source/administration/indexes.txt
@@ -44,7 +44,7 @@ all documents in a collection for documents that match the query.
       db.records.find( { user_id: 2 } )
 
    However, the following query, on the ``profile_url`` field is not
-   supported by this index::
+   supported by this index:
 
    .. code-block:: javascript
 
diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt
index 6353c5c7c4a..0461aab0233 100644
--- a/source/core/read-operations.txt
+++ b/source/core/read-operations.txt
@@ -34,7 +34,7 @@ In the :program:`mongo` shell, the :method:`find()
 <db.collection.find()>` and :method:`findOne()
 <db.collection.findOne()>` methods perform read operations. The
 :method:`find() <db.collection.find()>` method has the following
-syntax:
+syntax [#formal-query-structure]_:
 
 .. code-block:: javascript
 
@@ -69,7 +69,7 @@ syntax:
   necessarily consistent unless you specify a sort (:method:`sort()
   <cursor.sort()>`).
 
-For example, the following operation on the ``inventory`` collection,
+For example, the following operation on the ``inventory`` collection
 selects all documents where the ``type`` field equals ``'food'`` and
 the ``price`` field has a value less than ``9.95``. The projection
 limits the response to the ``item`` and ``qty``, and ``_id`` field:
@@ -93,6 +93,20 @@ For additional documentation and examples of the main MongoDB read
 operators, refer to the :doc:`/applications/read` page of the
 :doc:`/crud` section.
 
+.. [#formal-query-structure]
+   :method:`db.collection.find( \<query\>, \<projection\> )
+   <db.collection.find()>` is a wrapper for the more formal query
+   structure with the :operator:`$query` operator:
+
+   .. code-block:: javascript
+
+      db.collection.find( { $query: <query>, ... }, <projection> )
+
+   Within the formal structure, in addition to the :operator:`$query`
+   operator, you can use the :doc:`meta query operators
+   </reference/meta-query-operators>` to modify the behavior of the
+   query.
+
 .. _read-operations-query-document:
 .. _read-operations-query-argument:
 
@@ -411,7 +425,7 @@ the query used an index. This query:
 - returned 5 documents, as indicated by the :data:`n` field;
 
 - scanned 5 documents from the index, as indicated by the
-  :data:`nscanned`` field;
+  :data:`nscanned` field;
 
 - then read 5 full documents from the collection, as indicated by
   the :data:`nscannedObjects` field.
diff --git a/source/reference/meta-query-operators.txt b/source/reference/meta-query-operators.txt
index edbe2a6e2a9..6e0160bd21c 100644
--- a/source/reference/meta-query-operators.txt
+++ b/source/reference/meta-query-operators.txt
@@ -13,23 +13,26 @@ 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 form (for the :program:`mongo` shell):
+following forms (for the :program:`mongo` shell):
 
 .. code-block:: javascript
 
-   db.collection.find( { [QUERY] } )._addSpecial( [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. Many of the operators have
-corresponding :doc:`methods in the shell </reference/javascript>`. For
-the proposes of this reference, this document assumes the above form
-where possible.
+   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.
 
 Modifiers
 ---------
 
+Many of the operators have corresponding :doc:`methods
+in the shell </reference/javascript>`. 
+
 .. include:: operator/returnKey.txt
    :start-after: mongodb
 
@@ -42,6 +45,9 @@ Modifiers
 .. include:: operator/comment.txt
    :start-after: mongodb
 
+.. include:: operator/max.txt
+   :start-after: mongodb
+   
 .. include:: operator/min.txt
    :start-after: mongodb
 
diff --git a/source/reference/operator/comment.txt b/source/reference/operator/comment.txt
index 1edfed09536..57ee723d647 100644
--- a/source/reference/operator/comment.txt
+++ b/source/reference/operator/comment.txt
@@ -7,13 +7,12 @@ $comment
 .. operator:: $comment
 
    The :operator:`$comment` makes it possible to attach a comment to a
-   query. Because these comments propagate to the
-   :dbcommand:`profile` log, adding :operator:`$comment` modifiers can
-   make your profile data much easier to interpret and trace. Consider
-   the following example:
+   query. Because these comments propagate to the :dbcommand:`profile`
+   log, adding :operator:`$comment` modifiers can make your profile
+   data much easier to interpret and trace. Use one of the following
+   forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$comment" , "[COMMENT]" )
-
-   Here, ``[COMMENT]`` represents the text of the comment.
+      db.collection.find( { <QUERY> } )._addSpecial( "$comment", <comment to add> )
+      db.collection.find( { $query: { <QUERY> }, $comment: <comment to add> } )
diff --git a/source/reference/operator/explain.txt b/source/reference/operator/explain.txt
index 8b6b57208f8..151a84ff073 100644
--- a/source/reference/operator/explain.txt
+++ b/source/reference/operator/explain.txt
@@ -6,14 +6,19 @@ $explain
 
 .. operator:: $explain
 
-   Use the :operator:`$explain` operator to return a :term:`document`
-   that describes the process and indexes used to return the
-   query. This may provide useful insight when attempting to optimize
-   a query. Consider the following example:
+   :operator:`$explain` operator provides information on the query
+   plan. It returns a :ref:`document <explain-output>` that describes
+   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:
 
    .. code-block:: javascript
 
        db.collection.find()._addSpecial( "$explain", 1 )
+       db.collection.find( { $query: {}, $explain: 1 } )
 
    The JavaScript function :method:`cursor.explain()` provides equivalent
    functionality in the :program:`mongo` shell. See the following
diff --git a/source/reference/operator/hint.txt b/source/reference/operator/hint.txt
index 2590785e977..edaedad8134 100644
--- a/source/reference/operator/hint.txt
+++ b/source/reference/operator/hint.txt
@@ -9,13 +9,21 @@ $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 form:
+   the following operations:
 
    .. code-block:: javascript
 
        db.collection.find()._addSpecial( "$hint", { _id : 1 } )
+       db.collection.find( { $query: {}, $hint: { _id : 1 } } )
 
-   This operation returns all documents in the collection named
+   These are equivalent to the following :method:`cursor.hint()` method that
+   may be more familiar to you:
+
+   .. code-block:: javascript
+
+      db.collection.find().hint( { _id: 1 } )
+
+   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.
diff --git a/source/reference/operator/max.txt b/source/reference/operator/max.txt
index 09bb42b17f0..b8baa7a4c2d 100644
--- a/source/reference/operator/max.txt
+++ b/source/reference/operator/max.txt
@@ -6,22 +6,34 @@ $max
 
 .. operator:: $max
 
-   Specify a :operator:`$max` value to specify an upper boundary for
-   the value of a field. :program:`mongod` enforces this boundary with
-   an index of that field.
+   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 }``:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial("$max" , { value : 100 })
+       db.collection.find()._addSpecial( "$max", { age : 100 } )
+       db.collection.find( { $query: {}, $max: { age: 100 } } )
 
-   This operation above limits the documents returned to those that
-   match the query described by ``[QUERY]`` where the field
-   ``value`` is less than ``20``. :program:`mongod` infers the
-   index based on on the ``query`` unless specified by the
-   :method:`cursor.hint()` function.
+   These are equivalent to the following :method:`cursor.max()` method that
+   may be more familiar to you:
+
+   .. code-block:: javascript
+
+      db.collection.find().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.
 
    Use operation alone or in conjunction with :operator:`$min`
-   to limit results to a specific range.
+   to limit results to a specific range for the same index.
 
    .. note::
 
diff --git a/source/reference/operator/maxScan.txt b/source/reference/operator/maxScan.txt
index 0990c7e3c3c..d4bb2971e20 100644
--- a/source/reference/operator/maxScan.txt
+++ b/source/reference/operator/maxScan.txt
@@ -7,11 +7,12 @@ $maxScan
 .. operator:: $maxScan
 
    Constrains the query to only scan the specified number of documents
-   when fulfilling the query. Use the following form:
+   when fulfilling the query. Use one of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$maxScan" , 50 )
+      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.
diff --git a/source/reference/operator/min.txt b/source/reference/operator/min.txt
index 3af6c911abe..780ca0b67c1 100644
--- a/source/reference/operator/min.txt
+++ b/source/reference/operator/min.txt
@@ -6,22 +6,34 @@ $min
 
 .. operator:: $min
 
-   Specify a :operator:`$min` value to specify a lower boundary for
-   the value of a field. :program:`mongod` enforces this boundary with
-   an index of the field.
+   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 }``:
 
    .. code-block:: javascript
 
-      db.collection.find( { [QUERY] } )._addSpecial("$min" , { value : 20})
+      db.collection.find()._addSpecial("$min" , { age : 20 } )
+      db.collection.find( { $query: {}, $min: { age: 20 } } )
 
-   This operation above limits the documents returned to those that
-   match the query described by ``[QUERY]`` where the field
-   ``value`` is at least ``20``. :program:`mongod` infers the
-   index based on the ``query`` unless specified by the
-   :method:`cursor.hint()` function.
+   These are equivalent to the following :method:`cursor.min()` method that
+   may be more familiar to you:
 
-   Use operation alone or in conjunction with :operator:`$max`
-   to limit results to a specific range.
+   .. 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.
 
    .. note::
 
diff --git a/source/reference/operator/orderby.txt b/source/reference/operator/orderby.txt
index d8db9c86a82..1409e6b0d9c 100644
--- a/source/reference/operator/orderby.txt
+++ b/source/reference/operator/orderby.txt
@@ -7,24 +7,25 @@ $orderby
 .. operator:: $orderby
 
    The :operator:`$orderby` operator sorts the results of a query in
-   ascending or descending order. Consider the following syntax:
+   ascending or descending order. Consider the following operations:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$orderby", { age : -1} )
+      db.collection.find()._addSpecial( "$orderby", { age : -1 } )
+      db.collection.find( { $query: {}, $orderby: { age : -1 } } )
 
-   This is equivalent to the following :method:`cursor.sort()` method that
+   These are equivalent to the following :method:`cursor.sort()` method that
    may be more familiar to you:
 
    .. code-block:: javascript
 
       db.collection.find().sort( { age: -1 } )
 
-   Both of these examples return all documents in the collection named
-   ``collection`` sorted for in descending order from greatest to
-   smallest. Specify a value to :operator:`$orderby` of negative one
-   (e.g. ``-1``, as above) to sort in descending order or a positive
-   value (e.g. ``1``) to sort in ascending order.
+   These examples return all documents in the collection named
+   ``collection`` sorted by the ``age`` field in descending order.
+   Specify a value to :operator:`$orderby` of negative one (e.g.
+   ``-1``, as above) to sort in descending order or a positive value
+   (e.g. ``1``) to sort in ascending order.
 
    Unless you have a index for the specified key pattern, use
    :operator:`$orderby` in conjunction with :operator:`$maxScan` and/or
@@ -32,3 +33,5 @@ $orderby
    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
diff --git a/source/reference/operator/query.txt b/source/reference/operator/query.txt
index 57ccf06fc8e..c50031fb48f 100644
--- a/source/reference/operator/query.txt
+++ b/source/reference/operator/query.txt
@@ -7,15 +7,18 @@ $query
 .. operator:: $query
 
    The :operator:`$query` operator provides an interface to describe
-   queries. Consider the following operation.
+   queries. Consider the following operation:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$query" : { value : 100 } )
+      db.collection.find( { $query: { age : 25 } } )
 
    This is equivalent to the following :method:`db.collection.find()` method that
    may be more familiar to you:
 
    .. code-block:: javascript
 
-      db.collection.find( { value : 100 } )
+      db.collection.find( { age : 25 } )
+      
+   These operations return only those documents in the collection named
+   ``collection`` where the ``age`` field equals ``25``.
diff --git a/source/reference/operator/returnKey.txt b/source/reference/operator/returnKey.txt
index 5dc6fd69470..3125037446e 100644
--- a/source/reference/operator/returnKey.txt
+++ b/source/reference/operator/returnKey.txt
@@ -6,9 +6,12 @@ $returnKey
 
 .. operator:: $returnKey
 
-   Only return the index key (i.e. :term:`_id`) or keys for the
-   results of the query. Use the following form:
+   Only return the index key or keys for the results of the query. If
+   :operator:`$returnKey` is set to ``true`` and the query does not use
+   an index to perform the read operation, the returned documents will
+   not contain any fields. Use one of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial("$returnKey" , true )
+      db.collection.find( { <QUERY> } )._addSpecial( "$returnKey", true )
+      db.collection.find( { $query: { <QUERY> }, $returnKey: true } )
diff --git a/source/reference/operator/showDiskLoc.txt b/source/reference/operator/showDiskLoc.txt
index d165bc09f6a..f9f68483331 100644
--- a/source/reference/operator/showDiskLoc.txt
+++ b/source/reference/operator/showDiskLoc.txt
@@ -6,9 +6,11 @@ $showDiskLoc
 
 .. operator:: $showDiskLoc
 
-   Use the following modifier to display the disk location:
+   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:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial("$showDiskLoc" , true)
-
+      db.collection.find( { <QUERY> } )._addSpecial("$showDiskLoc" , true)
+      db.collection.find( { $query: { <QUERY> }, $showDiskLoc: true } )
diff --git a/source/reference/operator/snapshot.txt b/source/reference/operator/snapshot.txt
index 70b25d419c6..d050eadf20d 100644
--- a/source/reference/operator/snapshot.txt
+++ b/source/reference/operator/snapshot.txt
@@ -6,21 +6,19 @@ $snapshot
 
 .. operator:: $snapshot
 
-   The :operator:`$snapshot` operator ensures that the results
-   returned by a query:
+   The :operator:`$snapshot` operator prevents the cursor from
+   returning a document more than once because an intervening write
+   operation results in a move of the document.
 
-   - contains no duplicates.
-   - misses no objects.
-   - returns all matching objects that were present at the beginning
-     and the end of the query.
+   Even in snapshot mode, objects inserted or deleted during the
+   lifetime of the cursor may or may not be returned.
 
-   Snapshot mode does not guarantee the inclusion (or omission) of an
-   object present at the beginning of the query but not at the end
-   (due to an update.) Use the following syntax:
+   Use one of the following forms:
 
    .. code-block:: javascript
 
-      db.foo.find()._addSpecial( "$snapshot", true )
+      db.collection.find()._addSpecial( "$snapshot", true )
+      db.collection.find( { $query: {}, $snapshot: true } )
 
    The JavaScript function :method:`cursor.snapshot()` provides equivalent
    functionality in the :program:`mongo` shell. See the following
@@ -28,7 +26,8 @@ $snapshot
 
    .. code-block:: javascript
 
-      db.foo.find().snapshot()
+      db.collection.find().snapshot()
 
-   Do not use snapshot with :operator:`$hint`, or :operator:`$orderby`
-   (:method:`cursor.sort()`.)
+   The :operator:`$snapshot` operator traverses the index on the
+   ``_id`` field. Do **not** use :operator:`$snapshot` with
+   :operator:`$hint` or :operator:`$orderby` (:method:`cursor.sort()`.)

From 4397a2a1cb376be130cf5585adc093f2222ef671 Mon Sep 17 00:00:00 2001
From: kay <kay.kim@10gen.com>
Date: Mon, 10 Dec 2012 22:45:54 -0500
Subject: [PATCH 2/2] DOCS-799 incorporate scotts comments

---
 source/reference/meta-query-operators.txt | 25 ++++----
 source/reference/operator/comment.txt     |  4 +-
 source/reference/operator/explain.txt     | 15 ++---
 source/reference/operator/hint.txt        | 27 ++++----
 source/reference/operator/max.txt         | 74 +++++++++++++++------
 source/reference/operator/maxScan.txt     |  4 +-
 source/reference/operator/min.txt         | 78 +++++++++++++++++------
 source/reference/operator/orderby.txt     | 24 +++----
 source/reference/operator/returnKey.txt   |  4 +-
 source/reference/operator/showDiskLoc.txt | 19 ++++--
 source/reference/operator/snapshot.txt    | 30 ++++++---
 11 files changed, 197 insertions(+), 107 deletions(-)

diff --git a/source/reference/meta-query-operators.txt b/source/reference/meta-query-operators.txt
index 6e0160bd21c..9e1b5cecfe7 100644
--- a/source/reference/meta-query-operators.txt
+++ b/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
diff --git a/source/reference/operator/comment.txt b/source/reference/operator/comment.txt
index 57ee723d647..93b7bf35525 100644
--- a/source/reference/operator/comment.txt
+++ b/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> } )
diff --git a/source/reference/operator/explain.txt b/source/reference/operator/explain.txt
index 151a84ff073..921e1f5cb00 100644
--- a/source/reference/operator/explain.txt
+++ b/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 } )
diff --git a/source/reference/operator/hint.txt b/source/reference/operator/hint.txt
index edaedad8134..6be8ee200f8 100644
--- a/source/reference/operator/hint.txt
+++ b/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 } } )
diff --git a/source/reference/operator/max.txt b/source/reference/operator/max.txt
index b8baa7a4c2d..ad41801b526 100644
--- a/source/reference/operator/max.txt
+++ b/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.
diff --git a/source/reference/operator/maxScan.txt b/source/reference/operator/maxScan.txt
index d4bb2971e20..950578a35a5 100644
--- a/source/reference/operator/maxScan.txt
+++ b/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.
diff --git a/source/reference/operator/min.txt b/source/reference/operator/min.txt
index 780ca0b67c1..31d707275aa 100644
--- a/source/reference/operator/min.txt
+++ b/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.
diff --git a/source/reference/operator/orderby.txt b/source/reference/operator/orderby.txt
index 1409e6b0d9c..09896fd33e0 100644
--- a/source/reference/operator/orderby.txt
+++ b/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.
diff --git a/source/reference/operator/returnKey.txt b/source/reference/operator/returnKey.txt
index 3125037446e..f22838b4234 100644
--- a/source/reference/operator/returnKey.txt
+++ b/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 } )
diff --git a/source/reference/operator/showDiskLoc.txt b/source/reference/operator/showDiskLoc.txt
index f9f68483331..aca60a985a6 100644
--- a/source/reference/operator/showDiskLoc.txt
+++ b/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 } )
diff --git a/source/reference/operator/snapshot.txt b/source/reference/operator/snapshot.txt
index d050eadf20d..374714bce51 100644
--- a/source/reference/operator/snapshot.txt
+++ b/source/reference/operator/snapshot.txt
@@ -13,21 +13,33 @@ $snapshot
    Even in snapshot mode, objects inserted or deleted during the
    lifetime of the cursor may or may not be returned.
 
-   Use one of the following forms:
+   The :program:`mongo` shell provides the :method:`cursor.snapshot()`
+   method:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$snapshot", true )
-      db.collection.find( { $query: {}, $snapshot: true } )
+      db.collection.find().snapshot()
 
-   The JavaScript function :method:`cursor.snapshot()` 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().snapshot()
+      db.collection.find()._addSpecial( "$snapshot", true )
+      db.collection.find( { $query: {}, $snapshot: true } )
 
    The :operator:`$snapshot` operator traverses the index on the
-   ``_id`` field. Do **not** use :operator:`$snapshot` with
-   :operator:`$hint` or :operator:`$orderby` (:method:`cursor.sort()`.)
+   ``_id`` field [#snapshot-alternative]_.
+
+   .. warning::
+
+      - You cannot use :operator:`$snapshot` with :term:`sharded
+        collections <sharding>`.
+
+      - Do **not** use :operator:`$snapshot` with :operator:`$hint` or
+        :operator:`$orderby` (or the corresponding
+        :method:`cursor.hint()` and :method:`cursor.sort()` methods.)
+
+   .. [#snapshot-alternative]
+
+      You can achieve the :operator:`$snapshot` isolation behavior
+      using any *unique* index on invariable fields.