langref: document labeled blocks, labeled for, labeled while

closes #1327

doc/langref.html.in

@@ -2179,6 +2179,39 @@ test "@tagName" {
       sorts the order of the tag and union field by the largest alignment.
       </p>
       {#header_close#}
+      {#header_open|blocks#}
+      <p>
+      Blocks are used to limit the scope of variable declarations:
+      </p>
+      {#code_begin|test_err|undeclared identifier#}
+test "access variable after block scope" {
+    {
+        var x: i32 = 1;
+    }
+    x += 1;
+}
+      {#code_end#}
+      <p>Blocks are expressions. When labeled, <code>break</code> can be used
+      to return a value from the block:
+      </p>
+      {#code_begin|test#}
+const std = @import("std");
+const assert = std.debug.assert;
+
+test "labeled break from labeled block expression" {
+    var y: i32 = 123;
+
+    const x = blk: {
+        y += 1;
+        break :blk y;
+    };
+    assert(x == 124);
+    assert(y == 124);
+}
+      {#code_end#}
+      <p>Here, <code>blk</code> can be any name.</p>
+      {#see_also|Labeled while|Labeled for#}
+      {#header_close#}
       {#header_open|switch#}
       {#code_begin|test|switch#}
 const assert = @import("std").debug.assert;
@@ -2374,6 +2407,28 @@ fn rangeHasNumber(begin: usize, end: usize, number: usize) bool {
     } else false;
 }
       {#code_end#}
+      {#header_open|Labeled while#}
+      <p>When a <code>while</code> loop is labeled, it can be referenced from a <code>break</code>
+      or <code>continue</code> from within a nested loop:</p>
+      {#code_begin|test#}
+test "nested break" {
+    outer: while (true) {
+        while (true) {
+            break :outer;
+        }
+    }
+}
+
+test "nested continue" {
+    var i: usize = 0;
+    outer: while (i < 10) : (i += 1) {
+        while (true) {
+            continue :outer;
+        }
+    }
+}
+      {#code_end#}
+      {#header_close#}
       {#header_open|while with Optionals#}
       <p>
       Just like {#link|if#} expressions, while loops can take an optional as the
@@ -2560,6 +2615,37 @@ test "for else" {
     };
 }
       {#code_end#}
+      {#header_open|Labeled for#}
+      <p>When a <code>for</code> loop is labeled, it can be referenced from a <code>break</code>
+      or <code>continue</code> from within a nested loop:</p>
+      {#code_begin|test#}
+const std = @import("std");
+const assert = std.debug.assert;
+
+test "nested break" {
+    var count: usize = 0;
+    outer: for ([]i32{ 1, 2, 3, 4, 5 }) |_| {
+        for ([]i32{ 1, 2, 3, 4, 5 }) |_| {
+            count += 1;
+            break :outer;
+        }
+    }
+    assert(count == 1);
+}
+
+test "nested continue" {
+    var count: usize = 0;
+    outer: for ([]i32{ 1, 2, 3, 4, 5, 6, 7, 8 }) |_| {
+        for ([]i32{ 1, 2, 3, 4, 5 }) |_| {
+            count += 1;
+            continue :outer;
+        }
+    }
+
+    assert(count == 8);
+}
+      {#code_end#}
+      {#header_close#}
       {#header_open|inline for#}
       <p>
       For loops can be inlined. This causes the loop to be unrolled, which