DOCSP-22725 BACKPORT (#1240)

Author: Dave Cuthbert

source/includes/aggregation/fact-arrays-in-arguments.rst

@@ -0,0 +1,5 @@
+Aggregation expressions accept a variable number of arguments. These
+arguments are normally passed as an array. However, when the argument
+is a single value, you can simplify your code by passing the argument
+directly without wrapping it in an array. 
+

source/reference/operator/aggregation/isArray.txt

@@ -1,3 +1,5 @@
+.. _agg-expr-isArray:
+
 ======================
 $isArray (aggregation)
 ======================
@@ -34,47 +36,61 @@ The ``<expression>`` can be any valid :ref:`expression
 
 .. list-table::
    :header-rows: 1
-   :widths: 90 10
 
    * - Example
      - Results
+     - Notes
+
+   * - ``{ $isArray: "hello" }``
+     - ``false``
+     - ``"hello"`` is a string, passed as a string.
 
    * - ``{ $isArray: [ "hello" ] }``
      - ``false``
+     - ``"hello"`` is a string, passed as part of an argument array.
 
-   * - ``{ $isArray: [ [ "hello", "world" ] ] }``
+   * - ``{ $isArray: [ [ "hello" ] ] }``
      - ``true``
+     - ``[ "hello" ]`` is an array, passed as part of an argument array.
+
+.. note::
+
+   .. include:: /includes/aggregation/fact-arrays-in-arguments.rst
 
 Example
 -------
 
-A collection named ``warehouses`` contains the following documents:
+Create the ``warehouses`` collection:
 
 .. code-block:: javascript
 
-   { "_id" : 1, instock: [ "chocolate" ], ordered: [ "butter", "apples" ] }
-   { "_id" : 2, instock: [ "apples", "pudding", "pie" ] }
-   { "_id" : 3, instock: [ "pears", "pecans"], ordered: [ "cherries" ] }
-   { "_id" : 4, instock: [ "ice cream" ], ordered: [ ] }
+   db.warehouses.insertMany( [
+      { "_id" : 1, instock: [ "chocolate" ], ordered: [ "butter", "apples" ] },
+      { "_id" : 2, instock: [ "apples", "pudding", "pie" ] },
+      { "_id" : 3, instock: [ "pears", "pecans"], ordered: [ "cherries" ] },
+      { "_id" : 4, instock: [ "ice cream" ], ordered: [ ] }
+   ] )
 
-The following example checks if the ``instock`` and the ``ordered``
-fields are arrays before concatenating the two:
+Check if the ``instock`` and the ``ordered`` fields are arrays. If both
+fields are arrays, concatenate them:
 
 .. code-block:: javascript
 
-   db.warehouses.aggregate([
+   db.warehouses.aggregate( [
       { $project:
          { items: 
              { $cond:
                {
-                 if: { $and: [ { $isArray: "$instock" }, { $isArray: "$ordered" } ] },
+                 if: { $and: [ { $isArray: "$instock" },
+                               { $isArray: "$ordered" } 
+                             ] },
                  then: { $concatArrays: [ "$instock", "$ordered" ] },
                  else: "One or more fields is not an array."
                }
              }
          }
       }
-   ])
+   ] )
 
 .. code-block:: javascript