DOCSP-24399 cherry-pick/merge (#1782)

Author: kennethdyer

source/includes/fact-dbcommand-tip.rst

@@ -0,0 +1,10 @@
+
+.. tip::
+
+   In :program:`mongosh`, this command can also be run through the |method|.
+
+   Helper methods are convenient for :program:`mongosh` 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-mongosh-shell-method-alt.rst

@@ -0,0 +1,14 @@
+.. important:: ``mongosh`` Method
+
+   This page documents a :binary:`~bin.mongosh` 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 </>`.
+
+   For the legacy ``mongo`` shell documentation, refer to the
+   documentation for the corresponding MongoDB Server release:
+
+   - :v4.4:`mongo shell v4.4 </mongo>`
+   - :v4.2:`mongo shell v4.2 </mongo>`

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
+
 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
+
    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
+
    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
+
    The command has the following form:
-   
+
    .. code-block:: javascript
 
       { dropIndexes: <string>, index: <string|document|arrayofstrings>, writeConcern: <document>, comment: <any> }

source/reference/command/explain.txt

@@ -21,9 +21,10 @@ Definition
    :dbcommand:`findAndModify`, :dbcommand:`delete`,
    :dbcommand:`mapReduce`, 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
 
    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
-      :binary:`~bin.mongosh` 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
 
 Syntax
 ------

source/reference/command/findAndModify.txt

@@ -24,6 +24,9 @@ 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
+
    .. versionchanged:: 5.0
 
    The command has the following syntax:

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
+
    The command has the following syntax:
 
    .. code-block:: javascript