Document label_break_value in the reference

src/expressions/loop-expr.md

@@ -14,15 +14,18 @@
 [_PredicateLoopExpression_]: #predicate-loops
 [_PredicatePatternLoopExpression_]: #predicate-pattern-loops
 [_IteratorLoopExpression_]: #iterator-loops
+[_LabelBreakExpression_]: #label-expressions
 
-Rust supports four loop expressions:
+Rust supports five loop expressions:
 
 *   A [`loop` expression](#infinite-loops) denotes an infinite loop.
 *   A [`while` expression](#predicate-loops) loops until a predicate is false.
 *   A [`while let` expression](#predicate-pattern-loops) tests a pattern.
 *   A [`for` expression](#iterator-loops) extracts values from an iterator, looping until the iterator is empty.
+*   A [labelled `break` expression](#label-expressions) runs a loop exactly once, but allows exiting the loop early.
 
-All four types of loop support [`break` expressions](#break-expressions), [`continue` expressions](#continue-expressions), and [labels](#loop-labels).
+All five types of loop support [`break` expressions](#break-expressions), and [labels](#loop-labels).
+All except labelled `break` expressions support [`continue` expressions](#continue-expressions). 
 Only `loop` supports [evaluation to non-trivial values](#break-and-loop-values).
 
 ## Infinite loops
@@ -193,6 +196,18 @@ A loop expression may optionally have a _label_. The label is written as a lifet
 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).
 
+Labels follow the hygiene and shadowing rules of local variables. For example, this code will print "outer loop":
+
+```rust
+'a: loop {
+    'a: loop {
+        break 'a;
+    }
+    print!("outer loop");
+    break 'a;
+}
+```
+
 ## `break` expressions
 
 > **<sup>Syntax</sup>**\
@@ -226,6 +241,15 @@ Example:
 
 A `break` expression is only permitted in the body of a loop, and has one of the forms `break`, `break 'label` or ([see below](#break-and-loop-values)) `break EXPR` or `break 'label EXPR`.
 
+## Label expressions
+
+> **<sup>Syntax</sup>**\
+> _LabelBreakExpression_ :\
+> &nbsp;&nbsp; [LIFETIME_OR_LABEL] [_BlockExpression_]
+
+Label expressions are exactly like block expressions, except that they allow using `break` expressions within the block.
+Unlike other loops, `break` expressions within a label expression *must* have a label (i.e. the label is not optional).
+
 ## `continue` expressions
 
 > **<sup>Syntax</sup>**\