DOCS-4063: $comment support

config/htaccess.yaml

@@ -4843,6 +4843,13 @@ type: redirect
 outputs:
   - 'before-v2.4'
 ---
+from: /reference/operator/query/comment
+to: /reference/operator/query/
+code: 303
+type: redirect
+outputs:
+  - 'before-v2.4'
+---
 from: /core/bulk-inserts
 to: /core/bulk-write-operations
 code: 303

source/includes/fact-comment-reason.rst

@@ -0,0 +1,2 @@
+Because comments propagate to the :dbcommand:`profile` log, adding a comment
+can make your profile data much easier to interpret and trace.

source/includes/ref-toc-operator-query-comment.yaml

@@ -0,0 +1,4 @@
+name: ":query:`$comment`"
+file: /reference/operator/query/comment
+description: "Attaches a human-readable comment to a query predicate."
+...

source/reference/operator/meta/comment.txt

@@ -6,13 +6,20 @@ $comment
 
 .. operator:: $comment
 
-   The :operator:`$comment` makes it possible to attach a comment to a
-   query. Because these comments propagate to the :dbcommand:`profile`
-   log, adding :operator:`$comment` modifiers can make your profile
-   data much easier to interpret and trace. Use one of the following
-   forms:
+   The :operator:`$comment` meta-operator makes it possible to attach a comment
+   to a query in any context that :operator:`$query` may appear.
+
+   You can attach comments to queries in other contexts using the
+   :query:`$comment` operator.
+
+   .. include:: /includes/fact-comment-reason.rst
+
+   Use :operator:`$comment` in one of the following ways:
 
    .. code-block:: javascript
 
       db.collection.find( { <query> } )._addSpecial( "$comment", <comment> )
+      db.collection.find( { <query> } ).comment( <comment> )
       db.collection.find( { $query: { <query> }, $comment: <comment> } )
+
+.. seealso:: :query:`$comment`

source/reference/operator/query.txt

@@ -94,6 +94,20 @@ Array
 
       /reference/operator/query-array
 
+Comments
+~~~~~~~~
+
+.. only:: website
+
+   .. include:: /includes/toc/table-operator-query-comment.rst
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /reference/operator/query/comment
+
 Projection Operators
 --------------------
 

source/reference/operator/query/comment.txt

@@ -0,0 +1,52 @@
+========
+$comment
+========
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. query:: $comment
+
+   The :query:`$comment` query operator attaches a comment to any expression
+   taking a query predicate.
+
+   .. include:: /includes/fact-comment-reason.rst
+
+   The :query:`$comment` operator has the form:
+
+   .. code-block:: javascript
+
+      db.collection.find( { <query>, $comment: <comment> } )
+
+Examples
+--------
+
+Attach a Comment to ``find``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may use :query:`$comment` with :method:`~db.collection.find` in the following
+way:
+
+.. code-block:: javascript
+
+   db.records.find( { x: { $mod: [ 2, 0 ] },
+                    $comment: "Find even values" } )
+
+Attach a Comment to an Aggregation Expression
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :query:`$comment` operator also works with the
+:ref:`aggregation framework <aggregation-framework>`. The following example
+sums up the even values, sums up the odd values, and reports the two
+sums. A :query:`$comment` clarifies the function of the :pipeline:`$match` expression.
+
+.. code-block:: javascript
+
+   db.records.aggregate( [ { $match: { x: { $gt: 0 },
+                                       $comment: "Don't allow negative inputs." } },
+                           { $group : { _id: { $mod: [ "$x", 2 ] },
+                                        total: { $sum: "$x" } } } ] )
+
+.. seealso:: :operator:`$comment`

source/tutorial/aggregation-zip-code-data-set.txt

@@ -46,6 +46,8 @@ wrapper around the :dbcommand:`aggregate` database command. See the
 documentation for your :doc:`driver </applications/drivers>` for a
 more idiomatic interface for data aggregation operations.
 
+.. _aggregation-return-states-by-population:
+
 Return States with Populations above 10 Million
 -----------------------------------------------