From d438a999f490e27685768c96b16fc7b1da562738 Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Fri, 10 Oct 2014 14:55:30 -0400 Subject: [PATCH] DOCS-4063: $comment support --- config/htaccess.yaml | 7 +++ source/includes/fact-comment-reason.rst | 2 + .../ref-toc-operator-query-comment.yaml | 4 ++ source/reference/operator/meta/comment.txt | 17 ++++-- source/reference/operator/query.txt | 14 +++++ source/reference/operator/query/comment.txt | 52 +++++++++++++++++++ .../aggregation-zip-code-data-set.txt | 2 + 7 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 source/includes/fact-comment-reason.rst create mode 100644 source/includes/ref-toc-operator-query-comment.yaml create mode 100644 source/reference/operator/query/comment.txt diff --git a/config/htaccess.yaml b/config/htaccess.yaml index 34422251f65..690103f2b52 100644 --- a/config/htaccess.yaml +++ b/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 diff --git a/source/includes/fact-comment-reason.rst b/source/includes/fact-comment-reason.rst new file mode 100644 index 00000000000..8dffe8b1e80 --- /dev/null +++ b/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. diff --git a/source/includes/ref-toc-operator-query-comment.yaml b/source/includes/ref-toc-operator-query-comment.yaml new file mode 100644 index 00000000000..5f43438c7ee --- /dev/null +++ b/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." +... diff --git a/source/reference/operator/meta/comment.txt b/source/reference/operator/meta/comment.txt index 56970271c16..54030a7cefe 100644 --- a/source/reference/operator/meta/comment.txt +++ b/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( { } )._addSpecial( "$comment", ) + db.collection.find( { } ).comment( ) db.collection.find( { $query: { }, $comment: } ) + +.. seealso:: :query:`$comment` diff --git a/source/reference/operator/query.txt b/source/reference/operator/query.txt index 01fb50465b2..265f640cbc5 100644 --- a/source/reference/operator/query.txt +++ b/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 -------------------- diff --git a/source/reference/operator/query/comment.txt b/source/reference/operator/query/comment.txt new file mode 100644 index 00000000000..8f4eec37f33 --- /dev/null +++ b/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( { , $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 `. 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` diff --git a/source/tutorial/aggregation-zip-code-data-set.txt b/source/tutorial/aggregation-zip-code-data-set.txt index d45640c134e..a3b4a80b1a2 100644 --- a/source/tutorial/aggregation-zip-code-data-set.txt +++ b/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 ` for a more idiomatic interface for data aggregation operations. +.. _aggregation-return-states-by-population: + Return States with Populations above 10 Million -----------------------------------------------