Clarify the rules for variable shadowing in comprehensions

Closes #4862

2 files changed, 14 insertions, 7 deletions

diff --git a/system/doc/programming_examples/list_comprehensions.xml b/system/doc/programming_examples/list_comprehensions.xml
index f9ce57f478..84648ee543 100644
--- a/system/doc/programming_examples/list_comprehensions.xml
+++ b/system/doc/programming_examples/list_comprehensions.xml
@@ -190,6 +190,12 @@ select(X, L) ->  [Y || {X1, Y} <- L, X == X1].]]></code>
     <pre>
 > <input>select(b,[{a,1},{b,2},{c,3},{b,7}]).</input>
 [2,7]</pre>
+    <p>Also note that a variable in a generator pattern will shadow
+    a variable with the same name bound in a previous generator
+    pattern. For example:</p>
+    <pre>
+> <input>[{X,Y} || X &lt;- [1,2,3], X=Y &lt;- [a,b,c]].</input>
+[{a,a},{b,b},{c,c},{a,a},{b,b},{c,c},{a,a},{b,b},{c,c}]</pre>
     <p>A consequence of the rules for importing variables into a
       list comprehensions is that certain pattern matching operations
       must be moved into the filters and cannot be written directly
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index 382f9a8a8c..3ac4d85e91 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -1573,11 +1573,12 @@ end</pre>
       <item>A <em>filter</em> is an expression, which evaluates to
       <c>true</c> or <c>false</c>.</item>
     </list>
-    <p>The variables in the generator patterns, shadow variables in the function
-    clause, surrounding the list comprehensions.</p> <p>A list comprehension
-    returns a list, where the elements are the result of evaluating <c>Expr</c>
-    for each combination of generator list elements and bit string generator
-    elements, for which all filters are true.</p>
+    <p>The variables in the generator patterns shadow previously bound variables,
+    including variables bound in a previous generator pattern.</p>
+    <p>A list comprehension returns a list, where the elements are the
+    result of evaluating <c>Expr</c> for each combination of generator
+    list elements and bit string generator elements, for which all
+    filters are true.</p>
     <p><em>Example:</em></p>
     <pre>
 1> <input>[X*2 || X &lt;- [1,2,3]].</input>
@@ -1624,8 +1625,8 @@ end</pre>
       <item>A <em>filter</em> is an expression that evaluates to
       <c>true</c> or <c>false</c>.</item>
     </list>
-    <p>The variables in the generator patterns, shadow variables in
-      the function clause, surrounding the bit string comprehensions.</p>
+    <p>The variables in the generator patterns shadow previously bound variables,
+    including variables bound in a previous generator pattern.</p>
     <p>A bit string comprehension returns a bit string, which is 
       created by concatenating the results of evaluating <c>BitString</c> 
       for each combination of bit string generator elements, for which all