DOCS-4677: edits and cleanup

Author: Sam Kleinman

source/reference/method/db.collection.stats-options.yaml

@@ -8,9 +8,12 @@ name: scale
 type: number
 position: 1
 description: |
-  Identical to the scalar parameter of the same name.
+  The scale used in the output to display the sizes of items. By
+  default, output displays sizes in bytes. To display kilobytes rather
+  than bytes, specify a ``scale`` value of ``1024``.
 
   .. versionadded:: 2.8
+
 ---
 object:
   name: db.collection.stats
@@ -22,11 +25,13 @@ name: indexDetails
 type: boolean
 position: 2
 description: |
-  Specifies whether to display index details.
+  When ``true`` :method:`db.collection.stats()`` returns index details
+  in addition to the collection stats.
 
   Defaults to ``false``.
 
   .. versionadded:: 2.8
+
 ---
 object:
   name: db.collection.stats
@@ -38,10 +43,10 @@ name: indexDetailsField
 type: document
 position: 3
 description: |
-  Provided that ``indexDetails`` is set to ``true``, allows filtering of
-  index details by specifying the index ``key``, as returned by
-  :method:`~db.collection.getIndexes()`. Mutually exclusive with
-  ``indexDetailsName``
+  If ``indexDetails`` is ``true``, use ``indexDetailsField`` to filter
+  index details by specifying the index ``key``. Use
+  :method:`~db.collection.getIndexes()` to discover index keys. You
+  cannot use ``indexDetailsField`` with ``indexDetailsName``.
 
   .. versionadded:: 2.8
 
@@ -56,10 +61,10 @@ name: indexDetailsName
 type: string
 position: 4
 description: |
-  Provided that ``indexDetails`` is set to ``true``, allows filtering of
-  index details by specifying the index ``name``, as returned by
-  :method:`~db.collection.getIndexes()`. Mutually exclusive with
-  ``indexDetailsKey``
+  If ``indexDetails`` is ``true``, use ``indexDetailsName`` to filter
+  index details by specifying the index ``name``. Use
+  :method:`~db.collection.getIndexes()` to discover index names. You
+  cannot use ``indexDetailsName`` with ``indexDetailsField``.
 
   .. versionadded:: 2.8
 

source/reference/method/db.collection.stats-param.yaml

@@ -15,6 +15,7 @@ description: |
      .. versionchanged:: 2.8
         Legacy parameter format. Mutually exclusive with ``options`` as a
         document.
+
 ---
 object:
   name: db.collection.stats
@@ -31,4 +32,5 @@ description: |
   or filtering of index details.
 
   .. versionadded:: 2.8
+
 ...

source/reference/method/db.collection.stats.txt

@@ -7,6 +7,12 @@ db.collection.stats()
 Definition
 ----------
 
+.. db.coll.stats() only takes one argument. (2.8-series change) You
+   can either specify a number to use as the scale argument to
+   collStats, or a document specifying a set of options to the
+   helper. This change is contained in the implementation of the
+   helper and not in the underlying command.
+
 .. method:: db.collection.stats(scale)
 .. method:: db.collection.stats(options)
 
@@ -41,9 +47,12 @@ the ``order_date`` field, and expressing sizes in kilobytes:
 
 .. code-block:: javascript
 
-   db.orders.stats({scale:1024,
-                    indexDetails:true,
-                    indexKey:{order_date:1}})
+   db.orders.stats( { scale: 1024,
+                      indexDetails: true,
+                      indexKey: { order_date: 1 } } )
+
+Additional Information
+----------------------
 
-.. seealso:: :doc:`/reference/command/collStats` for an
-   overview of the output of this command.
+Consider the :doc:`/reference/command/collStats` document for an
+overview of the output of :method:`db.collection.stats()`.