From ef93a36cd5b783d50b595f5f7eea7422649081a7 Mon Sep 17 00:00:00 2001
From: Gordon Cassie <gordoncassie@gmail.com>
Date: Thu, 7 Dec 2023 13:51:03 -0800
Subject: [PATCH] Add comment. Split up if docs for optionals.

---
 doc/langref.html.in | 90 ++++++++++++++++++++++++---------------------
 1 file changed, 49 insertions(+), 41 deletions(-)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index dab4d48e0d..a1cb0d7ec0 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -4628,6 +4628,7 @@ test "while null capture" {
     }
     try expect(sum1 == 3);
 
+    // null capture with an else block
     var sum2: u32 = 0;
     numbers_left = 3;
     while (eventuallyNullSequence()) |value| {
@@ -4636,6 +4637,7 @@ test "while null capture" {
         try expect(sum2 == 3);
     }
 
+    // null capture with a continue expression
     var i: u32 = 0;
     var sum3: u32 = 0;
     numbers_left = 3;
@@ -4923,46 +4925,6 @@ test "if boolean" {
     }
 }
 
-test "if optional" {
-    // If expressions test for null.
-
-    const a: ?u32 = 0;
-    if (a) |value| {
-        try expect(value == 0);
-    } else {
-        unreachable;
-    }
-
-    const b: ?u32 = null;
-    if (b) |_| {
-        unreachable;
-    } else {
-        try expect(true);
-    }
-
-    // The else is not required.
-    if (a) |value| {
-        try expect(value == 0);
-    }
-
-    // To test against null only, use the binary equality operator.
-    if (b == null) {
-        try expect(true);
-    }
-
-    // Access the value by reference using a pointer capture.
-    var c: ?u32 = 3;
-    if (c) |*value| {
-        value.* = 2;
-    }
-
-    if (c) |value| {
-        try expect(value == 2);
-    } else {
-        unreachable;
-    }
-}
-
 test "if error union" {
     // If expressions test for errors.
     // Note the |err| capture on the else.
@@ -5007,6 +4969,51 @@ test "if error union" {
         unreachable;
     }
 }
+      {#code_end#}
+      {#header_open|if with Optionals#}
+
+      {#code_begin|test|test_if_optionals#}
+const expect = @import("std").testing.expect;
+
+test "if optional" {
+    // If expressions test for null.
+
+    const a: ?u32 = 0;
+    if (a) |value| {
+        try expect(value == 0);
+    } else {
+        unreachable;
+    }
+
+    const b: ?u32 = null;
+    if (b) |_| {
+        unreachable;
+    } else {
+        try expect(true);
+    }
+
+    // The else is not required.
+    if (a) |value| {
+        try expect(value == 0);
+    }
+
+    // To test against null only, use the binary equality operator.
+    if (b == null) {
+        try expect(true);
+    }
+
+    // Access the value by reference using a pointer capture.
+    var c: ?u32 = 3;
+    if (c) |*value| {
+        value.* = 2;
+    }
+
+    if (c) |value| {
+        try expect(value == 2);
+    } else {
+        unreachable;
+    }
+}
 
 test "if error union with optional" {
     // If expressions test for errors before unwrapping optionals.
@@ -5052,6 +5059,7 @@ test "if error union with optional" {
     }
 }
       {#code_end#}
+      {#header_close#}
       {#see_also|Optionals|Errors#}
       {#header_close#}
       {#header_open|defer#}
@@ -6338,7 +6346,7 @@ test "optional pointers" {
       {#code_end#}
       {#header_close#}
 
-      {#see_also|while with Optionals|if#}
+      {#see_also|while with Optionals|if with Optionals#}
       {#header_close#}
       {#header_open|Casting#}
       <p>