DOCSP-24399 collection interlink v4.2 (#1790)

* DOCSP-24399 Merge interlink from v4.4

* DOCSP-24399 Fixes build warnings

* DOCSP-24399 Fixes build warnings

Author: kennethdyer

source/includes/fact-dbcommand-tip.rst

@@ -0,0 +1,11 @@
+
+.. tip::
+
+   In the :program:`mongo` Shell, this command can also be run through the 
+   |method|.
+
+   Helper methods are convenient for :program:`mongo` users, but they may not
+   return the same level of information as database commands.  In cases where
+   the convenience is not needed or the additional return fields are required,
+   use the database command.
+

source/includes/fact-mongo-shell-method-alt.rst

@@ -0,0 +1,9 @@
+.. important:: ``mongo`` Shell Method
+
+   This page documents a :binary:`~bin.mongo` method. This is *not*
+   the documentation for database commands or language-specific drivers,
+   such as Node.js. To use the database command, see the |dbcommand|.
+
+   For MongoDB API drivers, refer to the language-specific
+   :driver:`MongoDB driver documentation </>`.
+

source/reference/command/aggregate.txt

@@ -20,6 +20,10 @@ Definition
    to process data from a collection or other source with a sequence of 
    stage-based manipulations.
 
+   .. |method| replace:: :method:`db.aggregate()` and 
+      :method:`db.collection.aggregate()` helper methods
+   .. include:: /includes/fact-dbcommand-tip.rst
+
 Syntax
 ------
 

source/reference/command/createIndexes.txt

@@ -17,6 +17,10 @@ Definition
 
    Builds one or more indexes on a collection.
 
+   .. |method| replace:: :method:`db.collection.createIndex()` and
+      :method:`db.collection.createIndexes()` helper methods.
+   .. include:: /includes/fact-dbcommand-tip.rst
+
    The :dbcommand:`createIndexes` command takes the following form:
 
    .. code-block:: javascript

source/reference/command/distinct.txt

@@ -20,6 +20,9 @@ Definition
    an array of the distinct values. The return document also contains
    an embedded document with query statistics and the query plan.
 
+   .. |method| replace:: :method:`db.collection.distinct()` helper method.
+   .. include:: /includes/fact-dbcommand-tip.rst
+
    The command takes the following form
 
    .. code-block:: javascript

source/reference/command/dropIndexes.txt

@@ -16,8 +16,12 @@ dropIndexes
    (except the index on the ``_id`` field) from the specified
    collection.
 
+   .. |method| replace:: :method:`db.collection.dropIndex()` and
+      :method:`db.collection.dropIndexes()` helper methods.
+   .. include:: /includes/fact-dbcommand-tip.rst
+
    The command has the following form:
-   
+
    .. code-block:: javascript
 
       { dropIndexes: <string>, index: <string|document|arrayofstrings>, writeConcern: <document>}

source/reference/command/explain.txt

@@ -21,9 +21,9 @@ Definition
    :dbcommand:`findAndModify`, :dbcommand:`delete`, and
    :dbcommand:`update`.
 
-   Although MongoDB provides the :dbcommand:`explain` command, the
-   preferred method for running :dbcommand:`explain` is to use the
-   :method:`db.collection.explain()` and :method:`cursor.explain()` helpers.
+   .. |method| replace:: :method:`db.collection.explain()` and 
+      :method:`cursor.explain()` helper methods
+   .. include:: /includes/fact-dbcommand-tip.rst
 
    The :dbcommand:`explain` command has the following syntax:
 

source/reference/command/find.txt

@@ -20,12 +20,9 @@ Definition
    Executes a query and returns the first batch of results and the
    cursor id, from which the client can construct a cursor.
 
-   .. tip::
-
-      Rather than run the :dbcommand:`find` command directly, you can
-      use the :method:`db.collection.find()` helper provided in the
-      :binary:`~bin.mongo` shell or the equivalent helper in the
-      drivers.
+   .. |method| replace:: :method:`db.collection.find()` or
+      :method:`db.collection.findOne()` helper methods
+   .. include:: /includes/fact-dbcommand-tip.rst
 
 Syntax
 ------

source/reference/command/findAndModify.txt

@@ -24,6 +24,11 @@ Definition
    modifications made on the update. To return the document with the
    modifications made on the update, use the ``new`` option.
 
+   .. |method| replace:: :method:`db.collection.findAndModify()` helper method
+   .. include:: /includes/fact-dbcommand-tip.rst
+
+   .. versionchanged:: 5.0
+
    The command has the following syntax:
 
    .. code-block:: none

source/reference/command/insert.txt

@@ -19,6 +19,10 @@ Definition
    returns a document containing the status of all inserts. The insert
    methods provided by the MongoDB drivers use this command internally.
 
+   .. |method| replace:: :method:`db.collection.insertOne()` and
+      :method:`db.collection.insertMany()` helper methods
+   .. include:: /includes/fact-dbcommand-tip.rst
+
    The command has the following syntax:
 
    .. code-block:: javascript

source/reference/command/listIndexes.txt

@@ -17,9 +17,11 @@ Definition
 
    Returns information about the indexes on the specified collection. Returned 
    index information includes the keys and options used to create the index. 
-   You can optionally set the batch size for the first batch of results. The :binary:`~bin.mongo` 
-   shell provides the :method:`db.collection.getIndexes()` helper.
+   You can optionally set the batch size for the first batch of results. 
 
+   .. |method| replace:: :method:`db.collection.getIndexes()` helper method
+   .. include:: /includes/fact-dbcommand-tip.rst
+   
 Syntax
 ------
 

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

@@ -15,13 +15,11 @@ Definition
 
 .. method:: db.collection.aggregate(pipeline, options)
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`aggregate` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Calculates aggregate values for the data in a collection or a :doc:`view </core/views>`.
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80

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

@@ -17,9 +17,8 @@ Definition
 
 .. method:: db.collection.createIndex(keys, options)
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`createIndexes` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Creates indexes on collections.
 
@@ -29,7 +28,6 @@ Definition
       <3.2-version-0-indexes>` indexes. To upgrade existing version 0
       indexes, see :ref:`3.2-version-0-indexes`.
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80
@@ -115,14 +113,6 @@ Definition
 
 
 
-
-   The :method:`db.collection.createIndex()` is a wrapper around the
-   :dbcommand:`createIndexes` command.
-
-   To minimize the impact of building an index on replica sets and
-   sharded clusters, use a rolling index build procedure as described
-   on :doc:`/tutorial/build-indexes-on-replica-sets`.
-
 .. _ensureIndex-options:
 .. _createIndex-options:
 

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

@@ -15,15 +15,13 @@ Definition
 
 .. method:: db.collection.createIndexes( [ keyPatterns ], options )
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`createIndexes` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    .. versionadded:: 3.2
 
    Creates one or more indexes on a collection.
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80
@@ -108,14 +106,6 @@ Definition
 
 
 
-
-   The :method:`db.collection.createIndexes()` is a wrapper around the
-   :dbcommand:`createIndexes` command.
-
-   To minimize the impact of building an index on replica sets and sharded
-   clusters, use a rolling index build procedure
-   as described on :doc:`/tutorial/build-indexes-on-replica-sets`.
-
 .. _createIndexes-method-options:
 
 Options

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

@@ -15,14 +15,14 @@ Definition
 
 .. method:: db.collection.distinct(field, query, options)
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`distinct` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Finds the distinct
    values for a specified field across a single collection or view and returns
    the results in an array.
 
+   This method takes the following parameters:
 
    .. list-table::
       :header-rows: 1
@@ -57,11 +57,6 @@ Definition
         - Optional. A document that specifies the options.  See :ref:`distinct-method-options`.
 
 
-   
-
-
-   The :method:`db.collection.distinct()` method provides a wrapper
-   around the :dbcommand:`distinct` command.
 
    .. include:: /includes/note-distinct-bson-limit-agg-alternative.rst
 

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

@@ -16,13 +16,11 @@ Definition
 .. method:: db.collection.dropIndex(index)
 
 
-   .. include:: /includes/fact-mongo-shell-method.rst
-
-
-   Drops or removes the specified index from a collection. The
-   :method:`db.collection.dropIndex()` method provides a wrapper around
-   the :dbcommand:`dropIndexes` command.
+   .. |dbcommand| replace:: :dbcommand:`dropIndexes` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
+   Drops or removes the specified index from a collection. 
+   
    .. note::
 
       - You cannot drop the default index on the ``_id`` field.
@@ -32,6 +30,10 @@ Definition
         <db.collection.dropIndex>` to drop all non-``_id`` indexes. Use
         :method:`db.collection.dropIndexes()` instead.
 
+   To get the index name or the index specification document for the
+   :method:`db.collection.dropIndex()` method, use the
+   :method:`db.collection.getIndexes()` method.
+
    The :method:`db.collection.dropIndex()` method takes the following
    parameter:
 

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

@@ -16,9 +16,8 @@ Definition
 
 .. method:: db.collection.dropIndexes()
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`dropIndexes` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Drops the specified index or indexes (except the index on the
    ``_id`` field) from a collection.
@@ -102,9 +101,6 @@ Definition
           **To drop multiple indexes** (Available starting in MongoDB
           4.2), specify an array of the index names.
 
-   The :method:`db.collection.dropIndexes()` is a wrapper around the
-   :dbcommand:`dropIndexes` command.
-   
 Behavior
 --------
 

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

@@ -15,9 +15,8 @@ Description
 
 .. method:: db.collection.explain()
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`explain` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Returns information on the query plan for the following methods:
 

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

@@ -15,14 +15,12 @@ Definition
 
 .. method:: db.collection.find(query, projection)
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`find` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Selects documents in a collection or view and returns a
    :term:`cursor` to the selected documents.
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80

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

@@ -19,17 +19,13 @@ Definition
 
 .. method:: db.collection.findAndModify(document)
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
-
+   .. |dbcommand| replace:: :dbcommand:`findAndModify` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Modifies and returns a single document. By default, the returned
    document does not include the modifications made on the update. To
    return the document with the modifications made on the update, use
-   the ``new`` option. The :method:`~db.collection.findAndModify()`
-   method is a shell helper around the :dbcommand:`findAndModify`
-   command.
+   the ``new`` option. 
 
    The :method:`~db.collection.findAndModify()` method has the following
    form:

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

@@ -15,9 +15,8 @@ Definition
 
 .. method:: db.collection.findOne(query, projection)
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`find` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Returns one document that satisfies the specified query criteria on
    the collection or :doc:`view </core/views>`. If multiple documents

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

@@ -15,12 +15,13 @@ Definition
 
 .. method:: db.collection.getIndexes()
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
+   .. |dbcommand| replace:: :dbcommand:`listIndexes` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Returns an array that holds a list of documents that identify and
    describe the existing indexes on the collection. You must call
+
+   You must call
    :method:`db.collection.getIndexes()` on a collection. For example:
 
    .. code-block:: javascript

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

@@ -15,11 +15,8 @@ Definition
 
 .. method:: db.collection.insertMany()
 
-
-   .. include:: /includes/fact-mongo-shell-method.rst
-
-
-   .. versionadded:: 3.2
+   .. |dbcommand| replace:: :dbcommand:`insert` command
+   .. include:: /includes/fact-mongo-shell-method-alt.rst
 
    Inserts multiple documents into a collection.