DOCS-1492 cursor.explain

source/reference/method/cursor.explain-param.yaml

@@ -0,0 +1,13 @@
+object:
+  name: cursor.explain()
+  type: method
+field:
+  optional: true
+  type: param
+name: verbose
+type: Boolean
+position: 1
+description: |
+  Specifies the level of detail to include in the output. If ``true`` or
+  ``1``, includes the ``allPlans`` and ``oldPlan`` fields in the output.
+...

source/reference/method/cursor.explain.txt

@@ -9,29 +9,27 @@ Definition
 
 .. method:: cursor.explain()
 
-   The :method:`cursor.explain()` method provides information on the
+   Provides information on the
    query plan. The query plan is the plan the server uses to find the
    matches for a query. This information may be useful when optimizing
-   a query.
+   a query. The :method:`~cursor.explain()` method returns a document
+   that describes the process used to return the query results.
 
-   :param boolean verbose:
+   The :method:`~cursor.explain()` method has the following form:
 
-          Specifies the level of detail to include in the output. If
-          ``true`` or ``1``, includes the ``allPlans`` and ``oldPlan``
-          fields in the output.
+   .. code-block:: javascript
 
-   :returns: A document that
-             describes the process used to return the query results.
+      db.collection.find().explain()
 
-   Retrieve the query plan by appending :method:`~cursor.explain()` to
-   a :method:`~db.collection.find()` query, as in the following
-   example:
+   The :method:`~cursor.explain()` method has the following parameter:
 
-   .. code-block:: javascript
+   .. include:: /reference/method/cursor.explain-param.rst
 
-      db.products.find().explain()
+   For an explanation of output, see
+   :ref:`explain-output-fields-sharded` and
+   :ref:`explain-output-fields-core`.
 
-   :method:`explain <cursor.explain()>` runs the actual query to
+   The :method:`~cursor.explain()` method runs the actual query to
    determine the result. Although there are some differences between
    running the query with :method:`explain <cursor.explain()>` and
    running without, generally, the performance will be similar between
@@ -57,13 +55,11 @@ Definition
    :method:`hint() <cursor.hint()>`, the query optimizer does not
    reevaluate the query plans.
 
-
    .. note::
 
       In some situations, the :method:`explain() <cursor.explain()>`
       operation may differ from the actual query plan used by MongoDB
       in a normal query.
-
       The :method:`explain() <cursor.explain()>` operation evaluates
       the set of query plans and reports on the winning plan for the
       query. In normal operations the query optimizer caches winning
@@ -84,6 +80,8 @@ Definition
 
       - :doc:`Current Operation Reporting </reference/method/db.currentOp>`
 
+.. _explain-output-fields-sharded:
+
 Output for Queries on Sharded Collections
 -----------------------------------------
 
@@ -202,6 +200,10 @@ For queries on a sharded collection, the output contains the
 Core Explain Output
 -------------------
 
+This section explains output for queries on collections that are *not
+sharded*. For queries on sharded collections, see
+:ref:`explain-output-fields-sharded`.
+
 .. data:: explain.cursor
 
    :data:`~explain.cursor` is a string that reports the type of cursor