DOCS-9365: Shell helper sh.shardCollection() takes options parameter

source/includes/apiargs-dbcommand-shardCollection-field.yaml

@@ -32,7 +32,7 @@ arg_name: field
 description: |
   When ``true``, the ``unique`` option ensures that the underlying index
   enforces a unique constraint. Hashed shard keys do not support unique
-  constraints.
+  constraints. Defaults to ``false``.
 
 interface: dbcommand
 name: unique
@@ -60,7 +60,8 @@ arg_name: field
 description: |
   If the collection specified to ``shardCollection``
   has a default :doc:`collation </reference/collation>`,
-  you *must* set {{role}} to ``{ locale : "simple"}``, or
+  you *must* include a collation document with
+  ``{ locale : "simple" }``, or
   the ``shardCollection`` command fails. At least one of the indexes
   whose fields support the shard key pattern must have the simple
   collation.

source/includes/apiargs-method-sh.shardCollection-options-param.yaml

@@ -0,0 +1,23 @@
+arg_name: param
+source:
+  file: apiargs-dbcommand-shardCollection-field.yaml
+  ref: numInitialChunks
+
+interface: method
+name: numInitialChunks
+operation: sh.shardCollection
+optional: true
+position: 1
+type: integer
+---
+arg_name: param
+source:
+  file: apiargs-dbcommand-shardCollection-field.yaml
+  ref: collation
+interface: method
+name: collation
+operation: sh.shardCollection
+optional: true
+position: 2
+type: document
+...

source/includes/apiargs-method-sh.shardCollection-param.yaml

@@ -28,7 +28,18 @@ source:
 interface: method
 name: unique
 operation: sh.shardCollection
-optional: false
+optional: true
 position: 3
 type: boolean
+---
+arg_name: param
+description: |
+  A document containing optional fields, including
+  ``numInitialChunks`` and ``collation``.
+interface: method
+name: options
+operation: sh.shardCollection
+optional: true
+position: 4
+type: document
 ...

source/includes/extracts-collation.yaml

@@ -166,6 +166,10 @@ content: |-
           | :method:`db.collection.updateMany()`,
           | :method:`db.collection.replaceOne()`
 
+      * - :dbcommand:`shardCollection`
+
+        - | :method:`sh.shardCollection()`
+
       * - 
 
         - Individual update, replace, and delete operations in

source/includes/fact-shardCollection-collation.rst

@@ -0,0 +1,14 @@
+Collation
+~~~~~~~~~
+
+.. versionchanged:: 3.4
+
+If the collection has a default :doc:`collation</reference/collation>`,
+the |command| command must include a ``collation`` parameter with the
+value ``{ locale: "simple" }``. For non-empty collections with a
+default collation, you must have at least one index with the simple
+collation whose fields support the shard key pattern.
+
+You do not need to specify the ``collation`` option for collections
+without a collation. If you do specify the collation option for
+a collection with no collation, it will have no effect.

source/reference/command/shardCollection.txt

@@ -84,21 +84,7 @@ If specifying ``unique: true``:
 See also :ref:`Sharded Collection and Unique Indexes
 <sharding-shard-key-unique>`
 
-Collation
-~~~~~~~~~
-
-.. versionchanged:: 3.4
-
-If the collection has a default :doc:`collation</reference/collation>`,
-your :dbcommand:`shardCollection` command must include a
-``collation`` parameter with the value ``{ locale: "simple" }``.
-For non-empty collections with a collation, you must have at
-least one index with the simple collation whose fields support the
-shard key pattern.
-
-You do not need to specify the ``collation`` option for collections
-without a collation. If you do specify the collation option for
-a collection with no collation, it will have no effect.
+.. include:: /includes/fact-shardCollection-collation.rst
 
 Example
 -------

source/reference/method/sh.shardCollection.txt

@@ -13,13 +13,19 @@ sh.shardCollection()
 Definition
 ----------
 
-.. method:: sh.shardCollection(namespace, key, unique)
+.. method:: sh.shardCollection(namespace, key, unique, options)
+
+   .. |command| replace:: :method:`sh.shardCollection`
 
    Shards a collection using the ``key`` as a the :term:`shard
    key`. :method:`sh.shardCollection()` takes the following arguments:
 
    .. include:: /includes/apiargs/method-sh.shardCollection-param.rst
 
+The ``options`` argument supports the following options:
+
+.. include:: /includes/apiargs/method-sh.shardCollection-options-param.rst
+
 Considerations
 --------------
 
@@ -54,16 +60,38 @@ If specifying ``unique: true``:
 
 See also :ref:`Sharded Collection and Unique Indexes
 <sharding-shard-key-unique>`
+
+.. include:: /includes/fact-shardCollection-collation.rst
 
-Example
--------
+Examples
+--------
+
+Simple Usage
+~~~~~~~~~~~~
 
-Given the ``people`` collection in the ``records`` database, the
-following command shards the collection by the ``zipcode`` field:
+Given a collection named ``people`` in a database named ``records``,
+the following command shards the collection by the
+``zipcode`` field:
 
 .. code-block:: javascript
 
-   sh.shardCollection("records.people", { zipcode: 1} )
+   sh.shardCollection("records.people", { zipcode: 1 } )
 
-.. seealso:: :dbcommand:`shardCollection`, :doc:`/sharding`
+Usage with Options
+~~~~~~~~~~~~~~~~~~
 
+Given a collection named ``contacts`` in a database named ``phonebook``,
+the following command:
+
+- Shards the collection by the ``last_name`` field.
+- Indicates that there is no unique constraint on the underlying
+  index.
+- Specifies ``5`` initial chunks.
+- Specifies a :doc:`collation</reference/collation>`.
+
+.. code-block:: javascript
+
+   sh.shardCollection("phonebook.contacts", { last_name: 1 }, false,
+                       { numInitialChunks: 5, collation: { locale: "simple" } } )
+
+.. seealso:: :dbcommand:`shardCollection`, :doc:`/sharding`