Improve labeled blocks documentation

* list labeled blocks in the namespaces page
* add an example
* improve wording

Author: est31

src/expressions/loop-expr.md

@@ -249,8 +249,27 @@ A `break` expression is only permitted in the body of a loop, and has one of the
 >    [_BlockExpression_]
 
 Labelled block 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).
-Unlike other loops, labelled block expressions *must* begin with a label.
+Unlike loops, `break` expressions within a labelled block expression *must* have a label (i.e. the label is not optional).
+Similarly, labelled block expressions *must* begin with a label.
+
+```rust
+# fn do_thing() {}
+# fn condition_not_met() -> bool { true }
+# fn do_next_thing() {}
+# fn do_last_thing() {}
+let result = 'block: {
+    do_thing();
+    if condition_not_met() {
+        break 'block 1;
+    }
+    do_next_thing();
+    if condition_not_met() {
+        break 'block 2;
+    }
+    do_last_thing();
+    3
+};
+```
 
 ## `continue` expressions
 

src/names/namespaces.md

@@ -52,6 +52,7 @@ The following is a list of namespaces, with their corresponding entities:
     * [Generic lifetime parameters]
 * Label Namespace
     * [Loop labels]
+    * [Block labels]
 
 An example of how overlapping names in different namespaces can be used unambiguously:
 
@@ -132,6 +133,7 @@ It is still an error for a [`use` import] to shadow another macro, regardless of
 [Attribute macros]: ../procedural-macros.md#attribute-macros
 [attributes]: ../attributes.md
 [bang-style macros]: ../macros.md
+[Block labels]: ../expressions/loop-expr.md#labelled-block-expressions
 [boolean]: ../types/boolean.md
 [Built-in attributes]: ../attributes.md#built-in-attributes-index
 [closure parameters]: ../expressions/closure-expr.md