From 3d7e282e88ffa5c1854e09f63b4645100a5efd84 Mon Sep 17 00:00:00 2001
From: Michael Paik <michael.paik@10gen.com>
Date: Fri, 16 Jan 2015 02:03:15 -0500
Subject: [PATCH] DOCS-4677 - options format for db.collection.stats()

---
 .../method/db.collection.stats-options.yaml   | 66 +++++++++++++++++++
 .../method/db.collection.stats-param.yaml     | 20 ++++++
 .../reference/method/db.collection.stats.txt  | 21 +++++-
 3 files changed, 104 insertions(+), 3 deletions(-)
 create mode 100644 source/reference/method/db.collection.stats-options.yaml

diff --git a/source/reference/method/db.collection.stats-options.yaml b/source/reference/method/db.collection.stats-options.yaml
new file mode 100644
index 00000000000..c889520b41a
--- /dev/null
+++ b/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
+
+...
\ No newline at end of file
diff --git a/source/reference/method/db.collection.stats-param.yaml b/source/reference/method/db.collection.stats-param.yaml
index 87ee5fc0cfb..f0a155fd19d 100644
--- a/source/reference/method/db.collection.stats-param.yaml
+++ b/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
 ...
diff --git a/source/reference/method/db.collection.stats.txt b/source/reference/method/db.collection.stats.txt
index bbba1d195b5..e1ceb575eb2 100644
--- a/source/reference/method/db.collection.stats.txt
+++ b/source/reference/method/db.collection.stats.txt
@@ -8,12 +8,17 @@ 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.
 
@@ -21,8 +26,8 @@ Definition
    around the database command
    :dbcommand:`collStats`.
 
-Example
--------
+Examples
+--------
 
 The following operation returns stats on the ``people`` collection:
 
@@ -30,5 +35,15 @@ The following operation returns stats on the ``people`` collection:
 
    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.