Improve information about loops

1) Moved 'while' section below 'loop', 'break', and 'continue'; 2) Added information to 'while' and 'for' loops that they interact with 'break' and 'continue' and may have a lifetime label. 3) Clarified labeling syntax on the infinite loops.

diff --git a/src/doc/reference.md b/src/doc/reference.md
index d918a320e63a909c3298c213cb2188ddab0492b0..0e00bf4f7994eda2bc41d065b6bc696b157efdbe 100644 (file)
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -3078,28 +3078,6 @@ fn ten_times<F>(f: F) where F: Fn(i32) {
 ten_times(|j| println!("hello, {}", j));
 ```
 
-### While loops
-
-```{.ebnf .gram}
-while_expr : [ lifetime ':' ] "while" no_struct_literal_expr '{' block '}' ;
-```
-
-A `while` loop begins by evaluating the boolean loop conditional expression.
-If the loop conditional expression evaluates to `true`, the loop body block
-executes and control returns to the loop conditional expression. If the loop
-conditional expression evaluates to `false`, the `while` expression completes.
-
-An example:
-
-```
-let mut i = 0;
-
-while i < 10 {
-    println!("hello");
-    i = i + 1;
-}
-```
-
 ### Infinite loops
 
 A `loop` expression denotes an infinite loop.
@@ -3108,10 +3086,11 @@ A `loop` expression denotes an infinite loop.
 loop_expr : [ lifetime ':' ] "loop" '{' block '}';
 ```
 
-A `loop` expression may optionally have a _label_. If a label is present, then
-labeled `break` and `continue` expressions nested within this loop may exit out
-of this loop or return control to its head. See [Break
-expressions](#break-expressions) and [Continue
+A `loop` expression may optionally have a _label_. The label is written as
+a lifetime preceding the loop expression, as in `'foo: loop{ }`. If a
+label is present, then labeled `break` and `continue` expressions nested
+within this loop may exit out of this loop or return control to its head.
+See [Break expressions](#break-expressions) and [Continue
 expressions](#continue-expressions).
 
 ### Break expressions
@@ -3123,7 +3102,7 @@ break_expr : "break" [ lifetime ];
 A `break` expression has an optional _label_. If the label is absent, then
 executing a `break` expression immediately terminates the innermost loop
 enclosing it. It is only permitted in the body of a loop. If the label is
-present, then `break foo` terminates the loop with label `foo`, which need not
+present, then `break 'foo` terminates the loop with label `'foo`, which need not
 be the innermost label enclosing the `break` expression, but must enclose it.
 
 ### Continue expressions
@@ -3137,12 +3116,39 @@ executing a `continue` expression immediately terminates the current iteration
 of the innermost loop enclosing it, returning control to the loop *head*. In
 the case of a `while` loop, the head is the conditional expression controlling
 the loop. In the case of a `for` loop, the head is the call-expression
-controlling the loop. If the label is present, then `continue foo` returns
-control to the head of the loop with label `foo`, which need not be the
+controlling the loop. If the label is present, then `continue 'foo` returns
+control to the head of the loop with label `'foo`, which need not be the
 innermost label enclosing the `break` expression, but must enclose it.
 
 A `continue` expression is only permitted in the body of a loop.
 
+### While loops
+
+```{.ebnf .gram}
+while_expr : [ lifetime ':' ] "while" no_struct_literal_expr '{' block '}' ;
+```
+
+A `while` loop begins by evaluating the boolean loop conditional expression.
+If the loop conditional expression evaluates to `true`, the loop body block
+executes and control returns to the loop conditional expression. If the loop
+conditional expression evaluates to `false`, the `while` expression completes.
+
+An example:
+
+```
+let mut i = 0;
+
+while i < 10 {
+    println!("hello");
+    i = i + 1;
+}
+```
+
+Like `loop` expressions, `while` loops can be controlled with `break` or
+`continue`, and may optionally have a _label_. See [infinite
+loops](#infinite-loops), [break expressions](#break-expressions), and
+[continue expressions](#continue-expressions) for more information.
+
 ### For expressions
 
 ```{.ebnf .gram}
@@ -3177,6 +3183,11 @@ for i in 0..256 {
 }
 ```
 
+Like `loop` expressions, `while` loops can be controlled with `break` or
+`continue`, and may optionally have a _label_. See [infinite
+loops](#infinite-loops), [break expressions](#break-expressions), and
+[continue expressions](#continue-expressions) for more information.
+
 ### If expressions
 
 ```{.ebnf .gram}