DOCS-4677 - options format for db.collection.stats()

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

@@ -0,0 +1,66 @@
+object:
+  name: db.collection.stats
+  type: method
+field:
+  optional: true
+  type: field
+name: scale
+type: number
+position: 1
+description: |
+  Identical to the scalar parameter of the same name.
+
+  .. versionadded:: 2.8
+---
+object:
+  name: db.collection.stats
+  type: method
+field:
+  optional: true
+  type: field
+name: indexDetails
+type: boolean
+position: 2
+description: |
+  Specifies whether to display index details.
+
+  Defaults to ``false``.
+
+  .. versionadded:: 2.8
+---
+object:
+  name: db.collection.stats
+  type: method
+field:
+  optional: true
+  type: field
+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``
+
+  .. versionadded:: 2.8
+
+---
+object:
+  name: db.collection.stats
+  type: method
+field:
+  optional: true
+  type: field
+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``
+
+  .. versionadded:: 2.8
+
+...

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

@@ -11,4 +11,24 @@ description: |
      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``.
+
+     .. versionchanged:: 2.8
+        Legacy parameter format. Mutually exclusive with ``options`` as a
+        document.
+---
+object:
+  name: db.collection.stats
+  type: method
+field:
+  optional: true
+  type: param
+name: options
+type: document
+position: 2
+description: |
+  Alternate option format. Mutually exclusive with ``scale`` as a
+  scalar parameter. The use of this format optionally allows suppression
+  or filtering of index details.
+
+  .. versionadded:: 2.8
 ...

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

@@ -8,27 +8,42 @@ Definition
 ----------
 
 .. method:: db.collection.stats(scale)
+.. method:: db.collection.stats(options)
 
    Returns statistics about the collection. The method includes
-   the following parameter:
+   the following parameters:
 
    .. include:: /reference/method/db.collection.stats-param.rst
 
+   The ``options`` document can contain the following fields and values:
+
+   .. include:: /reference/method/db.collection.stats-options.rst
+
    :returns: A :term:`document` that contains statistics
              on the specified collection.
 
    The :method:`~db.collection.stats()` method provides a wrapper
    around the database command
    :dbcommand:`collStats`.
 
-Example
--------
+Examples
+--------
 
 The following operation returns stats on the ``people`` collection:
 
 .. code-block:: javascript
 
    db.people.stats()
 
+The following operation returns stats on the ``orders`` collection,
+suppressing all index stats except for those of the ascending index on
+the ``order_date`` field, and expressing sizes in kilobytes:
+
+.. code-block:: javascript
+
+   db.orders.stats({scale:1024,
+                    indexDetails:true,
+                    indexKey:{order_date:1}})
+
 .. seealso:: :doc:`/reference/command/collStats` for an
    overview of the output of this command.