DOCS-1277 hint with index name

source/reference/method/cursor.hint.txt

@@ -6,13 +6,32 @@ cursor.hint()
 
 .. method:: cursor.hint(index)
 
-   :argument index: The specification for the index to "hint" or force
+   :argument index: The index to "hint" or force
                     MongoDB to use when performing the query.
 
+                    Specify the index either by the index name or by
+                    the index specification document. See
+                    :ref:`document-index-specification` for information
+                    on index specification documents.
+
    Call this method on a query to override MongoDB's default index
-   selection and query optimization process. The argument is an index
-   specification, like the argument to :method:`ensureIndex() <db.collection.ensureIndex()>`. Use
-   :method:`db.collection.getIndexes()` to return the list of current indexes on a
-   collection.
+   selection and query optimization process. Use
+   :method:`db.collection.getIndexes()` to return the list of current
+   indexes on a collection.
+
+   Consider the following operation:
+
+   .. code-block:: javascript
+
+      db.users.find().hint( { age: 1 } )
+
+   This operation returns all documents in the collection named
+   ``users`` using the index on the ``age`` field. 
+
+   You can also specify the index using the index name:
+
+   .. code-block:: javascript
+
+      db.users.find().hint( "age_1" )
 
-   .. seealso:: ":operator:`$hint`"
+   .. seealso:: :operator:`$hint`

source/reference/operator/hint.txt

@@ -6,23 +6,45 @@ $hint
 
 .. operator:: $hint
 
-   The :operator:`$hint` operator forces the :ref:`query optimizer <read-operations-query-optimization>` to
-   use a specific index to fulfill the query.  Use :operator:`$hint`
-   for testing query performance and indexing strategies. Consider
-   the following form:
+   The :operator:`$hint` operator forces the :ref:`query optimizer
+   <read-operations-query-optimization>` to use a specific index to
+   fulfill the query. Specify the index either by the index name or by
+   the index specification document. See
+   :ref:`document-index-specification` for information on index
+   specification documents.
+
+   Use :operator:`$hint` for testing query performance and indexing
+   strategies. The :program:`mongo` shell provides a helper method
+   :method:`~cursor.hint()` for the :operator:`$hint` operator.
+
+   Consider the following operation:
 
    .. code-block:: javascript
 
-      db.collection.find().hint( { age: 1 } )
+      db.users.find().hint( { age: 1 } )
 
    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.
+   ``users`` using the index on the ``age`` field.
 
    You can also specify the option in either of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$hint", { age : 1 } )
-      db.collection.find( { $query: {}, $hint: { age : 1 } } )
+      db.users.find()._addSpecial( "$hint", { age : 1 } )
+      db.users.find( { $query: {}, $hint: { age : 1 } } )
+
+   .. note::
+
+      To use :operator:`$explain` in conjunction with :operator:`$hint`
+      in the following form:
+
+      .. code-block:: javascript
+
+         db.users.find( { $query: {}, $hint: { age : 1 } } )
+
+      You must add the :operator:`$explain` option to the document, as
+      in the following:
+
+      .. code-block:: javascript
+
+         db.users.find( { $query: {}, $hint: { age : 1 }, $explain: 1 } )