Document return value of loop statement

doc/Language/control.pod

@@ -568,6 +568,21 @@ is equivalent to the C-ish idiom:
 
     loop (;;) {...}
 
+The C<loop> statement may be used to produce values from the result of each
+run of the attached block if it appears in lists:
+
+    (loop ( my $i = 0; $i++ < 3;) { $i * 2 }).say;               #-> "(2 4 6)"
+    my @a = (loop ( my $i = 0; $i++ < 3;) { $i * 2 }); @a.say;   #-> "[2 4 6]"
+    my @a = do loop ( my $i = 0; $i++ < 3;) { $i * 2 }); @a.say; # same thing
+
+Unlike a C<for> loop, one should not rely on whether returned values are produced
+lazily, for now.  It would probably be best to use C<eager> to guarantee that a
+loop whose return value may be used actually runs:
+
+    sub heads-in-a-row {
+        (eager loop (; 2.rand < 1;) { "heads".say })
+    }
+
 =head2 X<while, until|control flow,while until>
 
 The C<while> statement executes the block as long as its condition is