Merge pull request #3134 from threadless-screw/control-flow-loop

Fixes: #3107

Author: lizmat

doc/Language/control.pod6

@@ -890,18 +890,25 @@ C<given> can follow a statement to set the topic in the statement it follows.
 =head1 X<loop|control flow, loop>
 
 The C<loop> statement takes three statements in parentheses separated by C<;>
-that take the role of initializer, conditional and incrementer. The initializer
-is executed once and any variable declaration will spill into the surrounding
-block. The conditional is executed once per iteration and coerced to C<Bool>,
-if C<False> the loop is stopped. The incrementer is executed once per
-iteration. CAUTION: Even though the loop iterator variable is I<inside> the loop's
-parentheses, it is a lexical variable in the loop's I<outer or containing> scope and can
-be used in code following the loop.
-
-    loop (my $i = 0; $i < 10; $i++) {
+that take the roles of initializer, conditional and incrementer, respectively.
+The initializer is executed once before the conditional is first tested. In case
+the initializer involves a variable declaration, the variable is declared as a
+lexical variable in the loop's I<outer or containing> scope so that it can be
+used in code following the loop statement. The conditional is executed before
+each iteration and coerced to C<Bool>; if C<False> the loop is stopped. The
+incrementer is executed after each iteration, and before the conditional is
+tested again.
+
+    loop (my $i = 0; $i < 10; $i++) {       # A typical loop
         say $i;
     }
 
+    my @str = "However Long".comb;          # Our very own .char routine:
+    loop (my $l = 0;;) {                    # Declare $l in outer scope
+        last if !@str[$l++]                 # and count chars until we hit an
+    }                                       # undefined element (Any)
+    say "The string is {--$l} chars long.";
+
 The infinite loop does not require parentheses.
 
 =for code