From aa9c70bda63b3ab73b15746609831dafb96f56ff Mon Sep 17 00:00:00 2001
From: est31 <MTest31@outlook.com>
Date: Sun, 19 Mar 2023 15:34:09 +0100
Subject: [PATCH] Improve labeled blocks documentation

* list labeled blocks in the namespaces page
* add an example
* improve wording
---
 src/expressions/loop-expr.md | 23 +++++++++++++++++++++--
 src/names/namespaces.md      |  2 ++
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/expressions/loop-expr.md b/src/expressions/loop-expr.md
index 204207ee0..c8b93ea39 100644
--- a/src/expressions/loop-expr.md
+++ b/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
 > &nbsp;&nbsp; [_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
 
diff --git a/src/names/namespaces.md b/src/names/namespaces.md
index 14811697c..bb4409b73 100644
--- a/src/names/namespaces.md
+++ b/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