Commit 9e6ff71330

Andrew Kelley <andrew@ziglang.org>
2024-01-19 03:56:15
langref: delete Nested Container Tests section
This section documented how a buggy feature worked at one point in time but it's not a description of what is supposed to happen. What is supposed to happen is simple enough to not warrant any documentation about it. When a file is imported, all the test decls are supposed to be queued for analysis. Also, refAllDecls() is a hack which should not be celebrated or even mentioned in the language reference. closes #18042
1 parent 9b714e0
Changed files (1)
doc/langref.html.in
@@ -1173,74 +1173,6 @@ fn addOne(number: i32) i32 {
       </p>
       {#see_also|The Global Error Set|Grammar#}
       {#header_close#}
-      {#header_open|Nested Container Tests#}
-      <p>
-        When the <kbd>zig test</kbd> tool is building a test runner, only resolved {#syntax#}test{#endsyntax#}
-        declarations are included in the build. Initially, only the given Zig source file's top-level
-        declarations are resolved. Unless nested {#link|containers|Containers#} are referenced from a top-level test declaration,
-        nested container tests will not be resolved.
-      </p>
-      <p>
-        The code sample below uses the {#syntax#}std.testing.refAllDecls(@This()){#endsyntax#} function call to
-        reference all of the containers that are in the file including the imported Zig source file. The code
-        sample also shows an alternative way to reference containers using the {#syntax#}_ = C;{#endsyntax#}
-        syntax. This syntax tells the compiler to ignore the result of the expression on the right side of the
-        assignment operator.
-      </p>
-      {#code_begin|test|testing_nested_container_tests#}
-const std = @import("std");
-const expect = std.testing.expect;
-
-// Imported source file tests will run when referenced from a top-level test declaration.
-// The next line alone does not cause "testing_introduction.zig" tests to run.
-const imported_file = @import("testing_introduction.zig");
-
-test {
-    // To run nested container tests, either, call `refAllDecls` which will
-    // reference all declarations located in the given argument.
-    // `@This()` is a builtin function that returns the innermost container it is called from.
-    // In this example, the innermost container is this file (implicitly a struct).
-    std.testing.refAllDecls(@This());
-
-    // or, reference each container individually from a top-level test declaration.
-    // The `_ = C;` syntax is a no-op reference to the identifier `C`.
-    _ = S;
-    _ = U;
-    _ = @import("testing_introduction.zig");
-}
-
-const S = struct {
-    test "S demo test" {
-        try expect(true);
-    }
-
-    const SE = enum {
-        V,
-
-        // This test won't run because its container (SE) is not referenced.
-        test "This Test Won't Run" {
-            try expect(false);
-        }
-    };
-};
-
-const U = union { // U is referenced by the file's top-level test declaration
-    s: US,        // and US is referenced here; therefore, "U.Us demo test" will run
-
-    const US = struct {
-        test "U.US demo test" {
-            // This test is a top-level test declaration for the struct.
-            // The struct is nested (declared) inside of a union.
-            try expect(true);
-        }
-    };
-
-    test "U demo test" {
-        try expect(true);
-    }
-};
-      {#code_end#}
-      {#header_close#}
       {#header_open|Test Failure#}
       <p>
         The default test runner checks for an {#link|error|Errors#} returned from a test.