Add a bit more text about generators

1 files changed, 14 insertions, 10 deletions

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index ca342605..cebc0d88 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -524,6 +524,8 @@ sections:
           You can also use this on an object, and it will return all
           the values of the object.
 
+          Note that the iterator operator is a generator of values.
+
         examples:
           - program: '.[]'
             input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
@@ -561,6 +563,8 @@ sections:
           .bar`, produces both the "foo" fields and "bar" fields as
           separate outputs.
 
+          The `,` operator is one way to contruct generators.
+
         examples:
           - program: '.foo, .bar'
             input: '{"foo": 42, "bar": "something else", "baz": true}'
@@ -579,13 +583,13 @@ sections:
 
           The | operator combines two filters by feeding the output(s) of
           the one on the left into the input of the one on the right. It's
-          pretty much the same as the Unix shell's pipe, if you're used to
-          that.
+          similar to the Unix shell's pipe, if you're used to that.
 
           If the one on the left produces multiple results, the one on
           the right will be run for each of those results. So, the
           expression `.[] | .foo` retrieves the "foo" field of each
-          element of the input array.
+          element of the input array.  This is a cartesian product,
+          which can be surprising.
 
           Note that `.a.b.c` is the same as `.a | .b | .c`.
 
@@ -3118,19 +3122,19 @@ sections:
             array or an object), `range(0; 10)` generates the integers
             between 0 and 10, and so on.
 
-            Even the comma operator is a generator, generating first the
-            values generated by the expression to the left of the comma,
-            then for each of those, the values generate by the
-            expression on the right of the comma.
+            Even the comma operator is a generator, generating first
+            the values generated by the expression to the left of the
+            comma, then the values generated by the expression on the
+            right of the comma.
 
             The `empty` builtin is the generator that produces zero
             outputs.  The `empty` builtin backtracks to the preceding
             generator expression.
 
             All jq functions can be generators just by using builtin
-            generators.  It is also possible to define new generators
-            using only recursion and the comma operator.  If the
-            recursive call(s) is(are) "in tail position" then the
+            generators.  It is also possible to construct new generators
+            using only recursion and the comma operator.  If
+            recursive calls are "in tail position" then the
             generator will be efficient.  In the example below the
             recursive call by `_range` to itself is in tail position.
             The example shows off three advanced topics: tail recursion,