add docs and missing test case for merging error sets

See #367

3 files changed, 66 insertions, 1 deletions

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 3a7dbd1e90..290ed77e7d 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -3117,7 +3117,50 @@ test "error union" {
     comptime assert(@typeOf(foo).ErrorSet == error);
 }
       {#code_end#}
-      <p>TODO the <code>||</code> operator for error sets</p>
+      {#header_open|Merging Error Sets#}
+      <p>
+      Use the <code>||</code> operator to merge two error sets together. The resulting
+      error set contains the errors of both error sets. Doc comments from the left-hand
+      side override doc comments from the right-hand side. In this example, the doc
+      comments for <code>C.PathNotFound</code> is <code>A doc comment</code>.
+      </p>
+      <p>
+      This is especially useful for functions which return different error sets depending
+      on {#link|comptime#} branches. For example, the Zig standard library uses
+      <code>LinuxFileOpenError || WindowsFileOpenError</code> for the error set of opening
+      files.
+      </p>
+      {#code_begin|test#}
+const A = error{
+    NotDir,
+
+    /// A doc comment
+    PathNotFound,
+};
+const B = error{
+    OutOfMemory,
+
+    /// B doc comment
+    PathNotFound,
+};
+
+const C = A || B;
+
+fn foo() C!void {
+    return error.NotDir;
+}
+
+test "merge error sets" {
+    if (foo()) {
+        @panic("unexpected");
+    } else |err| switch (err) {
+        error.OutOfMemory => @panic("unexpected"),
+        error.PathNotFound => @panic("unexpected"),
+        error.NotDir => {},
+    }
+}
+      {#code_end#}
+      {#header_close#}
       {#header_open|Inferred Error Sets#}
       <p>
       Because many functions in Zig return a possible error, Zig supports inferring the error set.
diff --git a/test/behavior.zig b/test/behavior.zig
index 3341fe717d..eb8b643bb7 100644
--- a/test/behavior.zig
+++ b/test/behavior.zig
@@ -31,6 +31,7 @@ comptime {
     _ = @import("cases/incomplete_struct_param_tld.zig");
     _ = @import("cases/ir_block_deps.zig");
     _ = @import("cases/math.zig");
+    _ = @import("cases/merge_error_sets.zig");
     _ = @import("cases/misc.zig");
     _ = @import("cases/namespace_depends_on_compile_var/index.zig");
     _ = @import("cases/new_stack_call.zig");
diff --git a/test/cases/merge_error_sets.zig b/test/cases/merge_error_sets.zig
new file mode 100644
index 0000000000..189bd16a4d
--- /dev/null
+++ b/test/cases/merge_error_sets.zig
@@ -0,0 +1,21 @@
+const A = error{
+    PathNotFound,
+    NotDir,
+};
+const B = error{OutOfMemory};
+
+const C = A || B;
+
+fn foo() C!void {
+    return error.NotDir;
+}
+
+test "merge error sets" {
+    if (foo()) {
+        @panic("unexpected");
+    } else |err| switch (err) {
+        error.OutOfMemory => @panic("unexpected"),
+        error.PathNotFound => @panic("unexpected"),
+        error.NotDir => {},
+    }
+}