From 9e6ff713300295150a02c6ab12852d325d92559a Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 18 Jan 2024 19:56:15 -0700 Subject: [PATCH 1/5] 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 --- doc/langref.html.in | 68 --------------------------------------------- 1 file changed, 68 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 49faed4bd9..f774c0bfdc 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -1173,74 +1173,6 @@ fn addOne(number: i32) i32 {

{#see_also|The Global Error Set|Grammar#} {#header_close#} - {#header_open|Nested Container Tests#} -

- When the zig test 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. -

-

- 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. -

- {#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#}

The default test runner checks for an {#link|error|Errors#} returned from a test. From 8662c0ff43aad7191b063047c71384e868086d6f Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 18 Jan 2024 20:58:35 -0700 Subject: [PATCH 2/5] langref: avoid the ambiguous word "safe" See #2402 --- doc/langref.html.in | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index f774c0bfdc..f3cb0fbae8 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -2788,9 +2788,11 @@ test "volatile" {

{#header_close#}

- To convert one pointer type to another, use {#link|@ptrCast#}. This is an unsafe - operation that Zig cannot protect you against. Use {#syntax#}@ptrCast{#endsyntax#} only when other - conversions are not possible. + {#link|@ptrCast#} converts a pointer's element type to another. This + creates a new pointer that can cause undetectable illegal behavior + depending on the loads and stores that pass through it. Generally, other + kinds of type conversions are preferable to + {#syntax#}@ptrCast{#endsyntax#} if possible.

{#code_begin|test|test_pointer_casting#} const std = @import("std"); @@ -8592,7 +8594,8 @@ test "decl access by string" { 
{#syntax#}@floatFromInt(int: anytype) anytype{#endsyntax#}

Converts an integer to the closest floating point representation. The return type is the inferred result type. - To convert the other way, use {#link|@intFromFloat#}. This cast is always safe. + To convert the other way, use {#link|@intFromFloat#}. This operation is legal + for all values of all integer types.

{#header_close#} From 56db624643bb506d2b8fa9d81f4146c1b1f4e3c3 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 18 Jan 2024 21:14:44 -0700 Subject: [PATCH 3/5] langref: update Zig Build System section It's hosted externally for now. closes #18103 --- doc/langref.html.in | 149 +++----------------------------------------- 1 file changed, 7 insertions(+), 142 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index f3cb0fbae8..3f9957314f 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -10808,6 +10808,9 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; Some examples of tasks the build system can help with: