DOCS-920 add info to getShardDistribution method

Author: kay-kim

source/reference/javascript.txt

@@ -282,7 +282,7 @@ that you may use with collection objects.
 .. include:: method/getShardVersion.txt
    :start-after: mongodb
 
-.. include:: method/getShardDistribution.txt
+.. include:: method/db.collection.getShardDistribution.txt
    :start-after: mongodb
 
 .. include:: method/db.collection.stats.txt

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

@@ -0,0 +1,100 @@
+====================================
+db.collection.getShardDistribution()
+====================================
+
+.. default-domain:: mongodb
+
+.. method:: db.collection.getShardDistribution()
+
+   Prints the data distribution statistics for a :term:`sharded
+   <sharding>` collection. You must call the
+   :method:`~db.collection.getShardDistibution()` method on a sharded
+   collection, as in the following example:
+
+   .. code-block:: javascript
+
+      db.myShardedCollection.getShardDistribution()
+
+   In the example, the collection ``myShardedCollection`` has two
+   shards. The output displays both the individual shard distribution
+   information as well the total shard distribution:
+
+   .. code-block:: sh
+
+      Shard <shard-a> at <host-a>
+       data : <size-a> docs : <count-a> chunks : <number of chunks-a>
+       estimated data per chunk : <size-a>/<number of chunks-a>
+       estimated docs per chunk : <count-a>/<number of chunks-a>
+
+      Shard <shard-b> at <host-b>
+       data : <size-b> docs : <count-b> chunks : <number of chunks-b>
+       estimated data per chunk : <size-b>/<number of chunks-b>
+       estimated docs per chunk : <count-b>/<number of chunks-b>
+
+      Totals
+       data : <stats.size> docs : <stats.count> chunks : <calc total chunks>
+       Shard <shard-a> contains  <estDataPercent-a>% data, <estDocPercent-a>% docs in cluster, avg obj size on shard : stats.shards[ <shard-a> ].avgObjSize
+       Shard <shard-b> contains  <estDataPercent-b>% data, <estDocPercent-b>% docs in cluster, avg obj size on shard : stats.shards[ <shard-b> ].avgObjSize
+
+   The output information displays:
+   
+   - ``<shard-x>`` is a string value that returns the shard name.
+
+   - ``<host-x>`` is a string value that returns the host name(s).
+   
+   - ``<size-x>`` is a numeric value that returns the size of the data,
+     including the unit of measure (e.g. ``b``, ``Mb``).
+   
+   - ``<count-x>`` is a numeric value that returns the number of
+     documents in the shard.
+
+   - ``<number of chunks-x>`` is a numeric value that returns the
+     number of chunks in the shard.
+
+   - ``<size-x>/<number of chunks-x>`` is a calculated numeric value
+     that returns the estimated data size per chunk for the shard,
+     including the unit of measure (e.g. ``b``, ``Mb``).
+
+   - ``<count-x>/<number of chunks-x>`` is a calculated numeric value
+     that returns the estimated number of documents per chunk for the
+     shard.
+
+   - ``<stats.size>`` is a numeric value that returns the total size of
+     the data in the sharded collection, including the unit of measure.
+
+   - ``<stats.count>`` is a numeric value that returns the total number
+     of documents in the sharded collection.
+
+   - ``<calc total chunks>`` is a calculated numeric value that adds
+     the number of chunks from the shards, for example:
+
+     .. code-block:: sh
+
+        <calc total chunks> = <number of chunks-a> + <number of chunks-b> 
+
+   - ``<estDataPercent-x>`` is a calculated numeric value that
+     calculates, for each shard, its data size as the percentage of the
+     collection's total data size, for example:
+
+     .. code-block:: sh
+
+        <estDataPercent-x> = <size-x>/<stats.size>
+
+   - ``<estDocPercent-x>`` is a calculated numeric value that
+     calculates, for each shard, the number of documents as the
+     percentage of the total number of documents for the collection,
+     for example:
+
+     .. code-block:: sh
+     
+        <estDocPercent-x> = <count-x>/<stats.count>
+
+   - ``stats.shards[ <shard-x> ].avgObjSize`` is a numeric value that
+     returns the average object size, including the unit of measure,
+     for the shard.
+
+   .. seealso:: :doc:`/sharding`
+   
+.. COMMENT -- not sure if I should mention the source of the data:
+   ``shards`` collection and the ``chunks`` collection in the ``config`` database
+   and from the :method:`db.collection.stats()` method.