From a0c3de5bfe78d80d0daa570d27500f147d79c3ab Mon Sep 17 00:00:00 2001
From: Techatrix <19954306+Techatrix@users.noreply.github.com>
Date: Sun, 4 Sep 2022 22:12:37 +0200
Subject: [PATCH] update data/master.zig

---
 src/data/master.zig | 238 +++++++++++++++++++++++---------------------
 1 file changed, 125 insertions(+), 113 deletions(-)

diff --git a/src/data/master.zig b/src/data/master.zig
index 97b4824..2c49e08 100644
--- a/src/data/master.zig
+++ b/src/data/master.zig
@@ -43,7 +43,7 @@ pub const builtins = [_]Builtin{
         \\This function returns the number of bytes that this type should be aligned to for the current target to match the C ABI. When the child type of a pointer has this alignment, the alignment can be omitted from the type.
         \\
         \\```zig
-        \\const expect = @import("std").debug.assert;
+        \\const assert = @import("std").debug.assert;
         \\comptime {
         \\    assert(*u32 == *align(@alignOf(u32)) u32);
         \\}
@@ -76,7 +76,7 @@ pub const builtins = [_]Builtin{
         \\
         \\The provided `frame_buffer` must be large enough to fit the entire function frame. This size can be determined with [@frameSize](https://ziglang.org/documentation/master/#frameSize). To provide a too-small buffer invokes safety-checked [Undefined Behavior](https://ziglang.org/documentation/master/#Undefined-Behavior).
         \\
-        \\`result_ptr` is optional ([null](https://ziglang.org/documentation/master/#null) may be provided). If provided, the function call will write its result directly to the result pointer, which will be available to read after [await](https://ziglang.org/documentation/master/#Async-and-Await) completes. Any result location provided to `await` will copy the result from `result_ptr`.</p> {#code_begin|test|async_struct_field_fn_pointer#} const std = @import("std"); const expect = std.testing.expect; test "async fn pointer in a struct field" { var data: i32 = 1; const Foo = struct { bar: fn (*i32) callconv(.Async) void, }; var foo = Foo{ .bar = func }; var bytes: [64]u8 align(@alignOf(@Frame(func))) = undefined; const f = @asyncCall(&bytes, {}, foo.bar, .{&data}); try expect(data == 2); resume f; try expect(data == 4); } fn func(y: *i32) void { defer y.* += 2; y.* += 1; suspend {} }`<pre>
+        \\`result_ptr` is optional ([null](https://ziglang.org/documentation/master/#null) may be provided). If provided, the function call will write its result directly to the result pointer, which will be available to read after [await](https://ziglang.org/documentation/master/#Async-and-Await) completes. Any result location provided to `await` will copy the result from `result_ptr`.</p> {#code_begin|test|async_struct_field_fn_pointer#} {#backend_stage1#} const std = @import("std"); const expect = std.testing.expect; test "async fn pointer in a struct field" { var data: i32 = 1; const Foo = struct { bar: fn (*i32) callconv(.Async) void, }; var foo = Foo{ .bar = func }; var bytes: [64]u8 align(@alignOf(@Frame(func))) = undefined; const f = @asyncCall(&bytes, {}, foo.bar, .{&data}); try expect(data == 2); resume f; try expect(data == 4); } fn func(y: *i32) void { defer y.* += 2; y.* += 1; suspend {} }`
         ,
         .arguments = &.{
             "frame_buffer: []align(@alignOf(@Frame(anyAsyncFunction))) u8",
@@ -159,7 +159,7 @@ pub const builtins = [_]Builtin{
         \\  - Convert `f32` to `u32` bits
         \\  - Convert `i32` to `u32` preserving twos complement
         \\
-        \\Works at compile-time if `value` is known at compile time. It's a compile error to bitcast a struct to a scalar type of the same size since structs have undefined layout. However if the struct is packed then it works.
+        \\Works at compile-time if `value` is known at compile time. It's a compile error to bitcast a value of undefined layout; this means that, besides the restriction from types which possess dedicated casting builtins (enums, pointers, error sets), bare structs, error unions, slices, optionals, and any other type without a well-defined memory layout, also cannot be used in this operation.
         ,
         .arguments = &.{
             "comptime DestType: type",
@@ -224,7 +224,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\Fused multiply add, similar to `(a * b) + c`, except only rounds once, and is thus more accurate.
         \\
-        \\Supports Floats and Vectors of floats.
+        \\Supports [Floats](https://ziglang.org/documentation/master/#Floats) and [Vectors](https://ziglang.org/documentation/master/#Vectors) of floats.
         ,
         .arguments = &.{
             "comptime T: type",
@@ -235,10 +235,10 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@byteSwap",
-        .signature = "@byteSwap(comptime T: type, operand: T) T",
-        .snippet = "@byteSwap(${1:comptime T: type}, ${2:operand: T})",
+        .signature = "@byteSwap(operand: anytype) T",
+        .snippet = "@byteSwap(${1:operand: anytype})",
         .documentation =
-        \\`T` must be an integer type with bit count evenly divisible by 8.
+        \\`@TypeOf(operand)` must be an integer type or an integer vector type with bit count evenly divisible by 8.
         \\
         \\`operand` may be an [integer](https://ziglang.org/documentation/master/#Integers) or [vector](https://ziglang.org/documentation/master/#Vectors).
         \\
@@ -247,24 +247,22 @@ pub const builtins = [_]Builtin{
         \\Note that for the purposes of memory layout with respect to endianness, the integer type should be related to the number of bytes reported by [@sizeOf](https://ziglang.org/documentation/master/#sizeOf) bytes. This is demonstrated with `u24`. `@sizeOf(u24) == 4`, which means that a `u24` stored in memory takes 4 bytes, and those 4 bytes are what are swapped on a little vs big endian system. On the other hand, if `T` is specified to be `u24`, then only 3 bytes are reversed.
         ,
         .arguments = &.{
-            "comptime T: type",
-            "operand: T",
+            "operand: anytype",
         },
     },
     .{
         .name = "@bitReverse",
-        .signature = "@bitReverse(comptime T: type, integer: T) T",
-        .snippet = "@bitReverse(${1:comptime T: type}, ${2:integer: T})",
+        .signature = "@bitReverse(integer: anytype) T",
+        .snippet = "@bitReverse(${1:integer: anytype})",
         .documentation =
-        \\`T` accepts any integer type.
+        \\`@TypeOf(anytype)` accepts any integer type or integer vector type.
         \\
         \\Reverses the bitpattern of an integer value, including the sign bit if applicable.
         \\
         \\For example 0b10110110 (`u8 = 182`, `i8 = -74`) becomes 0b01101101 (`u8 = 109`, `i8 = 109`).
         ,
         .arguments = &.{
-            "comptime T: type",
-            "integer: T",
+            "integer: anytype",
         },
     },
     .{
@@ -362,10 +360,10 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@clz",
-        .signature = "@clz(comptime T: type, operand: T)",
-        .snippet = "@clz(${1:comptime T: type}, ${2:operand: T})",
+        .signature = "@clz(operand: anytype)",
+        .snippet = "@clz(${1:operand: anytype})",
         .documentation =
-        \\`T` must be an integer type.
+        \\`@TypeOf(operand)` must be an integer type or an integer vector type.
         \\
         \\`operand` may be an [integer](https://ziglang.org/documentation/master/#Integers) or [vector](https://ziglang.org/documentation/master/#Vectors).
         \\
@@ -376,8 +374,7 @@ pub const builtins = [_]Builtin{
         \\If `operand` is zero, `@clz` returns the bit width of integer type `T`.
         ,
         .arguments = &.{
-            "comptime T: type",
-            "operand: T",
+            "operand: anytype",
         },
     },
     .{
@@ -479,7 +476,7 @@ pub const builtins = [_]Builtin{
         \\
         \\will output:
         \\
-        \\If all `@compileLog` calls are removed or not encountered by analysis, the program compiles successfully and the generated executable prints:</p> {#code_begin|test|without_compileLog#} const print = @import("std").debug.print; const num1 = blk: { var val1: i32 = 99; val1 = val1 + 1; break :blk val1; }; test "main" { print("Runtime in main, num1 = {}.\n", .{num1}); }`<pre>
+        \\If all `@compileLog` calls are removed or not encountered by analysis, the program compiles successfully and the generated executable prints:</p> {#code_begin|test|without_compileLog#} const print = @import("std").debug.print; const num1 = blk: { var val1: i32 = 99; val1 = val1 + 1; break :blk val1; }; test "main" { print("Runtime in main, num1 = {}.\n", .{num1}); }`
         ,
         .arguments = &.{
             "args: ...",
@@ -487,10 +484,10 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@ctz",
-        .signature = "@ctz(comptime T: type, operand: T)",
-        .snippet = "@ctz(${1:comptime T: type}, ${2:operand: T})",
+        .signature = "@ctz(operand: anytype)",
+        .snippet = "@ctz(${1:operand: anytype})",
         .documentation =
-        \\`T` must be an integer type.
+        \\`@TypeOf(operand)` must be an integer type or an integer vector type.
         \\
         \\`operand` may be an [integer](https://ziglang.org/documentation/master/#Integers) or [vector](https://ziglang.org/documentation/master/#Vectors).
         \\
@@ -501,8 +498,7 @@ pub const builtins = [_]Builtin{
         \\If `operand` is zero, `@ctz` returns the bit width of integer type `T`.
         ,
         .arguments = &.{
-            "comptime T: type",
-            "operand: T",
+            "operand: anytype",
         },
     },
     .{
@@ -671,7 +667,7 @@ pub const builtins = [_]Builtin{
         \\export fn foo() void {}
         \\```
         \\
-        \\Note that even when using `export`, `@"foo"` syntax can be used to choose any string for the symbol name:
+        \\Note that even when using `export`, the `@"foo"` syntax for [identifiers](https://ziglang.org/documentation/master/#Identifiers) can be used to choose any string for the symbol name:
         \\
         \\```zig
         \\export fn @"A function name that is a complete sentence."() void {}
@@ -718,7 +714,7 @@ pub const builtins = [_]Builtin{
         .signature = "@field(lhs: anytype, comptime field_name: []const u8) (field)",
         .snippet = "@field(${1:lhs: anytype}, ${2:comptime field_name: []const u8})",
         .documentation =
-        \\Performs field access by a compile-time string. Works on both fields and declarations.</p> {#code_begin|test|field_decl_access_by_string#} const std = @import("std"); const Point = struct { x: u32, y: u32, pub var z: u32 = 1; }; test "field access by string" { const expect = std.testing.expect; var p = Point{ .x = 0, .y = 0 }; @field(p, "x") = 4; @field(p, "y") = @field(p, "x") + 1; try expect(@field(p, "x") == 4); try expect(@field(p, "y") == 5); } test "decl access by string" { const expect = std.testing.expect; try expect(@field(Point, "z") == 1); @field(Point, "z") = 2; try expect(@field(Point, "z") == 2); }`<pre>
+        \\Performs field access by a compile-time string. Works on both fields and declarations.</p> {#code_begin|test|field_decl_access_by_string#} const std = @import("std"); const Point = struct { x: u32, y: u32, pub var z: u32 = 1; }; test "field access by string" { const expect = std.testing.expect; var p = Point{ .x = 0, .y = 0 }; @field(p, "x") = 4; @field(p, "y") = @field(p, "x") + 1; try expect(@field(p, "x") == 4); try expect(@field(p, "y") == 5); } test "decl access by string" { const expect = std.testing.expect; try expect(@field(Point, "z") == 1); @field(Point, "z") = 2; try expect(@field(Point, "z") == 2); }`
         ,
         .arguments = &.{
             "lhs: anytype",
@@ -782,7 +778,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\This function returns the frame type of a function. This works for [Async Functions](https://ziglang.org/documentation/master/#Async-Functions) as well as any function without a specific calling convention.
         \\
-        \\This type is suitable to be used as the return type of [async](https://ziglang.org/documentation/master/#Async-and-Await) which allows one to, for example, heap-allocate an async function frame:</p> {#code_begin|test|heap_allocated_frame#} const std = @import("std"); test "heap allocated frame" { const frame = try std.heap.page_allocator.create(@Frame(func)); frame.* = async func(); } fn func() void { suspend {} }`<pre>
+        \\This type is suitable to be used as the return type of [async](https://ziglang.org/documentation/master/#Async-and-Await) which allows one to, for example, heap-allocate an async function frame:</p> {#code_begin|test|heap_allocated_frame#} {#backend_stage1#} const std = @import("std"); test "heap allocated frame" { const frame = try std.heap.page_allocator.create(@Frame(func)); frame.* = async func(); } fn func() void { suspend {} }`
         ,
         .arguments = &.{
             "func: anytype",
@@ -803,22 +799,23 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@frameSize",
-        .signature = "@frameSize() usize",
-        .snippet = "@frameSize()",
+        .signature = "@frameSize(func: anytype) usize",
+        .snippet = "@frameSize(${1:func: anytype})",
         .documentation =
         \\This is the same as `@sizeOf(@Frame(func))`, where `func` may be runtime-known.
         \\
         \\This function is typically used in conjunction with [@asyncCall](https://ziglang.org/documentation/master/#asyncCall).
         ,
-        .arguments = &.{},
+        .arguments = &.{
+            "func: anytype",
+        },
     },
     .{
         .name = "@hasDecl",
         .signature = "@hasDecl(comptime Container: type, comptime name: []const u8) bool",
         .snippet = "@hasDecl(${1:comptime Container: type}, ${2:comptime name: []const u8})",
         .documentation =
-        \\Returns whether or not a [struct](https://ziglang.org/documentation/master/#struct), [enum](https://ziglang.org/documentation/master/#enum), or [union](https://ziglang.org/documentation/master/#union) has a declaration matching `name`.</p> {#code_begin|test|hasDecl#} const std = @import("std"); const expect = std.testing.expect; const Foo = struct { nope: i32, pub var blah = "xxx"; const hi = 1; }; test "@hasDecl" { try expect(@hasDecl(Foo, "blah")); // Even though `hi` is private, @hasDecl returns true because this test is // in the same file scope as Foo. It would return false if Foo was declared // in a different file. try expect(@hasDecl(Foo, "hi")); // @hasDecl is for declarations; not fields. try expect(!@hasDecl(Foo, "nope")); try expect(!@hasDecl(Foo, "nope1234")); }`<pre>
-        \\      
+        \\Returns whether or not a [struct](https://ziglang.org/documentation/master/#struct), [enum](https://ziglang.org/documentation/master/#enum), or [union](https://ziglang.org/documentation/master/#union) has a declaration matching `name`.</p> {#code_begin|test|hasDecl#} const std = @import("std"); const expect = std.testing.expect; const Foo = struct { nope: i32, pub var blah = "xxx"; const hi = 1; }; test "@hasDecl" { try expect(@hasDecl(Foo, "blah")); // Even though `hi` is private, @hasDecl returns true because this test is // in the same file scope as Foo. It would return false if Foo was declared // in a different file. try expect(@hasDecl(Foo, "hi")); // @hasDecl is for declarations; not fields. try expect(!@hasDecl(Foo, "nope")); try expect(!@hasDecl(Foo, "nope1234")); }`
         ,
         .arguments = &.{
             "comptime Container: type",
@@ -857,6 +854,7 @@ pub const builtins = [_]Builtin{
         \\The following packages are always available:
         \\  - `@import("std")` - Zig Standard Library
         \\  - `@import("builtin")` - Target-specific information The command `zig build-exe --show-builtin` outputs the source to stdout for reference.
+        \\  - `@import("root")` - Points to the root source file This is usually `src/main.zig` but it depends on what file is chosen to be built.
         ,
         .arguments = &.{
             "comptime path: []u8",
@@ -869,6 +867,16 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\Converts an integer to another integer while keeping the same numerical value. Attempting to convert a number which is out of range of the destination type results in safety-protected [Undefined Behavior](https://ziglang.org/documentation/master/#Undefined-Behavior).
         \\
+        \\```zig
+        \\test "integer cast panic" {
+        \\    var a: u16 = 0xabcd;
+        \\    var b: u8 = @intCast(u8, a);
+        \\    _ = b;
+        \\}
+        \\```
+        \\
+        \\To truncate the significant bits of a number out of range of the destination type, use [@truncate](https://ziglang.org/documentation/master/#truncate).
+        \\
         \\If `T` is `comptime_int`, then this is semantically equivalent to [Type Coercion](https://ziglang.org/documentation/master/#Type-Coercion).
         ,
         .arguments = &.{
@@ -922,7 +930,7 @@ pub const builtins = [_]Builtin{
         .signature = "@intToPtr(comptime DestType: type, address: usize) DestType",
         .snippet = "@intToPtr(${1:comptime DestType: type}, ${2:address: usize})",
         .documentation =
-        \\Converts an integer to a [pointer](https://ziglang.org/documentation/master/#Pointers). To convert the other way, use [@ptrToInt](https://ziglang.org/documentation/master/#ptrToInt).
+        \\Converts an integer to a [pointer](https://ziglang.org/documentation/master/#Pointers). To convert the other way, use [@ptrToInt](https://ziglang.org/documentation/master/#ptrToInt). Casting an address of 0 to a destination type which in not [optional](https://ziglang.org/documentation/master/#Optional-Pointers) and does not have the `allowzero` attribute will result in a [Pointer Cast Invalid Null](https://ziglang.org/documentation/master/#Pointer-Cast-Invalid-Null) panic when runtime safety checks are enabled.
         \\
         \\If the destination pointer type does not allow address zero and `address` is zero, this invokes safety-checked [Undefined Behavior](https://ziglang.org/documentation/master/#Undefined-Behavior).
         ,
@@ -1035,8 +1043,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\This function increases the size of the Wasm memory identified by `index` by `delta` in units of unsigned number of Wasm pages. Note that each Wasm page is 64KB in size. On success, returns previous memory size; on failure, if the allocation fails, returns -1.
         \\
-        \\This function is a low level intrinsic with no safety mechanisms usually useful for allocator designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use something like `@import("std").heap.WasmPageAllocator`.</p> {#code_begin|test|wasmMemoryGrow#} const std = @import("std"); const native_arch = @import("builtin").target.cpu.arch; const expect = std.testing.expect; test "@wasmMemoryGrow" { if (native_arch != .wasm32) return error.SkipZigTest; var prev = @wasmMemorySize(0); try expect(prev == @wasmMemoryGrow(0, 1)); try expect(prev + 1 == @wasmMemorySize(0)); }`<pre>
-        \\      
+        \\This function is a low level intrinsic with no safety mechanisms usually useful for allocator designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use something like `@import("std").heap.WasmPageAllocator`.</p> {#code_begin|test|wasmMemoryGrow#} const std = @import("std"); const native_arch = @import("builtin").target.cpu.arch; const expect = std.testing.expect; test "@wasmMemoryGrow" { if (native_arch != .wasm32) return error.SkipZigTest; var prev = @wasmMemorySize(0); try expect(prev == @wasmMemoryGrow(0, 1)); try expect(prev + 1 == @wasmMemorySize(0)); }`
         ,
         .arguments = &.{
             "index: u32",
@@ -1048,7 +1055,7 @@ pub const builtins = [_]Builtin{
         .signature = "@mod(numerator: T, denominator: T) T",
         .snippet = "@mod(${1:numerator: T}, ${2:denominator: T})",
         .documentation =
-        \\Modulus division. For unsigned integers this is the same as `numerator % denominator`. Caller guarantees `denominator > 0`.
+        \\Modulus division. For unsigned integers this is the same as `numerator % denominator`. Caller guarantees `denominator > 0`, otherwise the operation will result in a [Remainder Division by Zero](https://ziglang.org/documentation/master/#Remainder-Division-by-Zero) when runtime safety checks are enabled.
         \\  - `@mod(-5, 3) == 1`
         \\  - `(@divFloor(a, b) * b) + @mod(a, b) == a`
         \\
@@ -1090,10 +1097,10 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@popCount",
-        .signature = "@popCount(comptime T: type, operand: T)",
-        .snippet = "@popCount(${1:comptime T: type}, ${2:operand: T})",
+        .signature = "@popCount(operand: anytype)",
+        .snippet = "@popCount(${1:operand: anytype})",
         .documentation =
-        \\`T` must be an integer type.
+        \\`@TypeOf(operand)` must be an integer type.
         \\
         \\`operand` may be an [integer](https://ziglang.org/documentation/master/#Integers) or [vector](https://ziglang.org/documentation/master/#Vectors).
         \\
@@ -1102,8 +1109,7 @@ pub const builtins = [_]Builtin{
         \\If `operand` is a [comptime](https://ziglang.org/documentation/master/#comptime)-known integer, the return type is `comptime_int`. Otherwise, the return type is an unsigned integer or vector of unsigned integers with the minimum number of bits that can represent the bit count of the integer type.
         ,
         .arguments = &.{
-            "comptime T: type",
-            "operand: T",
+            "operand: anytype",
         },
     },
     .{
@@ -1115,7 +1121,7 @@ pub const builtins = [_]Builtin{
         \\
         \\The `ptr` argument may be any pointer type and determines the memory address to prefetch. This function does not dereference the pointer, it is perfectly legal to pass a pointer to invalid memory to this function and no illegal behavior will result.
         \\
-        \\The `options` argument is the following struct:</p> {#code_begin|syntax|builtin#} /// This data structure is used by the Zig language code generation and /// therefore must be kept in sync with the compiler implementation. pub const PrefetchOptions = struct { /// Whether the prefetch should prepare for a read or a write. rw: Rw = .read, /// 0 means no temporal locality. That is, the data can be immediately /// dropped from the cache after it is accessed. /// /// 3 means high temporal locality. That is, the data should be kept in /// the cache as it is likely to be accessed again soon. locality: u2 = 3, /// The cache that the prefetch should be preformed on. cache: Cache = .data, pub const Rw = enum { read, write, }; pub const Cache = enum { instruction, data, }; };`<pre>
+        \\The `options` argument is the following struct:</p> {#code_begin|syntax|builtin#} /// This data structure is used by the Zig language code generation and /// therefore must be kept in sync with the compiler implementation. pub const PrefetchOptions = struct { /// Whether the prefetch should prepare for a read or a write. rw: Rw = .read, /// 0 means no temporal locality. That is, the data can be immediately /// dropped from the cache after it is accessed. /// /// 3 means high temporal locality. That is, the data should be kept in /// the cache as it is likely to be accessed again soon. locality: u2 = 3, /// The cache that the prefetch should be preformed on. cache: Cache = .data, pub const Rw = enum { read, write, }; pub const Cache = enum { instruction, data, }; };`
         ,
         .arguments = &.{
             "ptr: anytype",
@@ -1158,7 +1164,7 @@ pub const builtins = [_]Builtin{
         .signature = "@rem(numerator: T, denominator: T) T",
         .snippet = "@rem(${1:numerator: T}, ${2:denominator: T})",
         .documentation =
-        \\Remainder division. For unsigned integers this is the same as `numerator % denominator`. Caller guarantees `denominator > 0`.
+        \\Remainder division. For unsigned integers this is the same as `numerator % denominator`. Caller guarantees `denominator > 0`, otherwise the operation will result in a [Remainder Division by Zero](https://ziglang.org/documentation/master/#Remainder-Division-by-Zero) when runtime safety checks are enabled.
         \\  - `@rem(-5, 3) == -2`
         \\  - `(@divTrunc(a, b) * b) + @rem(a, b) == a`
         \\
@@ -1184,16 +1190,16 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@select",
-        .signature = "@select(comptime T: type, pred: std.meta.Vector(len, bool), a: std.meta.Vector(len, T), b: std.meta.Vector(len, T)) std.meta.Vector(len, T)",
-        .snippet = "@select(${1:comptime T: type}, ${2:pred: std.meta.Vector(len, bool)}, ${3:a: std.meta.Vector(len, T)}, ${4:b: std.meta.Vector(len, T)})",
+        .signature = "@select(comptime T: type, pred: @Vector(len, bool), a: @Vector(len, T), b: @Vector(len, T)) @Vector(len, T)",
+        .snippet = "@select(${1:comptime T: type}, ${2:pred: @Vector(len, bool)}, ${3:a: @Vector(len, T)}, ${4:b: @Vector(len, T)})",
         .documentation =
         \\Selects values element-wise from `a` or `b` based on `pred`. If `pred[i]` is `true`, the corresponding element in the result will be `a[i]` and otherwise `b[i]`.
         ,
         .arguments = &.{
             "comptime T: type",
-            "pred: std.meta.Vector(len, bool)",
-            "a: std.meta.Vector(len, T)",
-            "b: std.meta.Vector(len, T)",
+            "pred: @Vector(len, bool)",
+            "a: @Vector(len, T)",
+            "b: @Vector(len, T)",
         },
     },
     .{
@@ -1209,19 +1215,19 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@setCold",
-        .signature = "@setCold(is_cold: bool)",
-        .snippet = "@setCold(${1:is_cold: bool})",
+        .signature = "@setCold(comptime is_cold: bool)",
+        .snippet = "@setCold(${1:comptime is_cold: bool})",
         .documentation =
         \\Tells the optimizer that a function is rarely called.
         ,
         .arguments = &.{
-            "is_cold: bool",
+            "comptime is_cold: bool",
         },
     },
     .{
         .name = "@setEvalBranchQuota",
-        .signature = "@setEvalBranchQuota(new_quota: u32)",
-        .snippet = "@setEvalBranchQuota(${1:new_quota: u32})",
+        .signature = "@setEvalBranchQuota(comptime new_quota: u32)",
+        .snippet = "@setEvalBranchQuota(${1:comptime new_quota: u32})",
         .documentation =
         \\Changes the maximum number of backwards branches that compile-time code execution can use before giving up and making a compile error.
         \\
@@ -1238,18 +1244,16 @@ pub const builtins = [_]Builtin{
         \\}
         \\```
         \\
-        \\Now we use `@setEvalBranchQuota`:</p> {#code_begin|test|setEvalBranchQuota#} test "foo" { comptime { @setEvalBranchQuota(1001); var i = 0; while (i < 1001) : (i += 1) {} } }`<pre>
-        \\
-        \\      
+        \\Now we use `@setEvalBranchQuota`:</p> {#code_begin|test|setEvalBranchQuota#} test "foo" { comptime { @setEvalBranchQuota(1001); var i = 0; while (i < 1001) : (i += 1) {} } }`
         ,
         .arguments = &.{
-            "new_quota: u32",
+            "comptime new_quota: u32",
         },
     },
     .{
         .name = "@setFloatMode",
-        .signature = "@setFloatMode(mode: @import(\"std\").builtin.FloatMode)",
-        .snippet = "@setFloatMode(${1:mode: @import(\"std\").builtin.FloatMode})",
+        .signature = "@setFloatMode(comptime mode: @import(\"std\").builtin.FloatMode)",
+        .snippet = "@setFloatMode(${1:comptime mode: @import(\"std\").builtin.FloatMode})",
         .documentation =
         \\Sets the floating point mode of the current scope. Possible values are:
         \\
@@ -1272,13 +1276,13 @@ pub const builtins = [_]Builtin{
         \\The floating point mode is inherited by child scopes, and can be overridden in any scope. You can set the floating point mode in a struct or module scope by using a comptime block.
         ,
         .arguments = &.{
-            "mode: @import(\"std\").builtin.FloatMode",
+            "comptime mode: @import(\"std\").builtin.FloatMode",
         },
     },
     .{
         .name = "@setRuntimeSafety",
-        .signature = "@setRuntimeSafety(safety_on: bool) void",
-        .snippet = "@setRuntimeSafety(${1:safety_on: bool})",
+        .signature = "@setRuntimeSafety(comptime safety_on: bool) void",
+        .snippet = "@setRuntimeSafety(${1:comptime safety_on: bool})",
         .documentation =
         \\Sets whether runtime safety checks are enabled for the scope that contains the function call.
         \\
@@ -1309,7 +1313,7 @@ pub const builtins = [_]Builtin{
         \\Note: it is [planned](https://github.com/ziglang/zig/issues/978) to replace `@setRuntimeSafety` with `@optimizeFor`
         ,
         .arguments = &.{
-            "safety_on: bool",
+            "comptime safety_on: bool",
         },
     },
     .{
@@ -1319,7 +1323,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\Performs the left shift operation (`<<`). For unsigned integers, the result is [undefined](https://ziglang.org/documentation/master/#undefined) if any 1 bits are shifted out. For signed integers, the result is [undefined](https://ziglang.org/documentation/master/#undefined) if any bits that disagree with the resultant sign bit are shifted out.
         \\
-        \\The type of `shift_amt` is an unsigned integer with `log2(T.bit_count)` bits. This is because `shift_amt >= T.bit_count` is undefined behavior.
+        \\The type of `shift_amt` is an unsigned integer with `log2(@typeInfo(T).Int.bits)` bits. This is because `shift_amt >= @typeInfo(T).Int.bits` is undefined behavior.
         ,
         .arguments = &.{
             "value: T",
@@ -1333,7 +1337,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\Performs `result.* = a << b`. If overflow or underflow occurs, stores the overflowed bits in `result` and returns `true`. If no overflow or underflow occurs, returns `false`.
         \\
-        \\The type of `shift_amt` is an unsigned integer with `log2(T.bit_count)` bits. This is because `shift_amt >= T.bit_count` is undefined behavior.
+        \\The type of `shift_amt` is an unsigned integer with `log2(@typeInfo(T).Int.bits)` bits. This is because `shift_amt >= @typeInfo(T).Int.bits` is undefined behavior.
         ,
         .arguments = &.{
             "comptime T: type",
@@ -1349,7 +1353,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\Performs the right shift operation (`>>`). Caller guarantees that the shift will not shift any 1 bits out.
         \\
-        \\The type of `shift_amt` is an unsigned integer with `log2(T.bit_count)` bits. This is because `shift_amt >= T.bit_count` is undefined behavior.
+        \\The type of `shift_amt` is an unsigned integer with `log2(@typeInfo(T).Int.bits)` bits. This is because `shift_amt >= @typeInfo(T).Int.bits` is undefined behavior.
         ,
         .arguments = &.{
             "value: T",
@@ -1358,8 +1362,8 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@shuffle",
-        .signature = "@shuffle(comptime E: type, a: std.meta.Vector(a_len, E), b: std.meta.Vector(b_len, E), comptime mask: std.meta.Vector(mask_len, i32)) std.meta.Vector(mask_len, E)",
-        .snippet = "@shuffle(${1:comptime E: type}, ${2:a: std.meta.Vector(a_len, E)}, ${3:b: std.meta.Vector(b_len, E)}, ${4:comptime mask: std.meta.Vector(mask_len, i32)})",
+        .signature = "@shuffle(comptime E: type, a: @Vector(a_len, E), b: @Vector(b_len, E), comptime mask: @Vector(mask_len, i32)) @Vector(mask_len, E)",
+        .snippet = "@shuffle(${1:comptime E: type}, ${2:a: @Vector(a_len, E)}, ${3:b: @Vector(b_len, E)}, ${4:comptime mask: @Vector(mask_len, i32)})",
         .documentation =
         \\Constructs a new [vector](https://ziglang.org/documentation/master/#Vectors) by selecting elements from `a` and `b` based on `mask`.
         \\
@@ -1371,14 +1375,13 @@ pub const builtins = [_]Builtin{
         \\
         \\If `a` or `b` is `undefined`, it is equivalent to a vector of all `undefined` with the same length as the other vector. If both vectors are `undefined`, `@shuffle` returns a vector with all elements `undefined`.
         \\
-        \\`E` must be an [integer](https://ziglang.org/documentation/master/#Integers), [float](https://ziglang.org/documentation/master/#Floats), [pointer](https://ziglang.org/documentation/master/#Pointers), or `bool`. The mask may be any vector length, and its length determines the result length.</p> {#code_begin|test|vector_shuffle#} const std = @import("std"); const Vector = std.meta.Vector; const expect = std.testing.expect; test "vector @shuffle" { const a: Vector(7, u8) = [_]u8{ 'o', 'l', 'h', 'e', 'r', 'z', 'w' }; const b: Vector(4, u8) = [_]u8{ 'w', 'd', '!', 'x' }; // To shuffle within a single vector, pass undefined as the second argument. // Notice that we can re-order, duplicate, or omit elements of the input vector const mask1: Vector(5, i32) = [_]i32{ 2, 3, 1, 1, 0 }; const res1: Vector(5, u8) = @shuffle(u8, a, undefined, mask1); try expect(std.mem.eql(u8, &@as([5]u8, res1), "hello")); // Combining two vectors const mask2: Vector(6, i32) = [_]i32{ -1, 0, 4, 1, -2, -3 }; const res2: Vector(6, u8) = @shuffle(u8, a, b, mask2); try expect(std.mem.eql(u8, &@as([6]u8, res2), "world!")); }`<pre>
-        \\      
+        \\`E` must be an [integer](https://ziglang.org/documentation/master/#Integers), [float](https://ziglang.org/documentation/master/#Floats), [pointer](https://ziglang.org/documentation/master/#Pointers), or `bool`. The mask may be any vector length, and its length determines the result length.</p> {#code_begin|test|vector_shuffle#} const std = @import("std"); const expect = std.testing.expect; test "vector @shuffle" { const a = @Vector(7, u8){ 'o', 'l', 'h', 'e', 'r', 'z', 'w' }; const b = @Vector(4, u8){ 'w', 'd', '!', 'x' }; // To shuffle within a single vector, pass undefined as the second argument. // Notice that we can re-order, duplicate, or omit elements of the input vector const mask1 = @Vector(5, i32){ 2, 3, 1, 1, 0 }; const res1: @Vector(5, u8) = @shuffle(u8, a, undefined, mask1); try expect(std.mem.eql(u8, &@as([5]u8, res1), "hello")); // Combining two vectors const mask2 = @Vector(6, i32){ -1, 0, 4, 1, -2, -3 }; const res2: @Vector(6, u8) = @shuffle(u8, a, b, mask2); try expect(std.mem.eql(u8, &@as([6]u8, res2), "world!")); }`
         ,
         .arguments = &.{
             "comptime E: type",
-            "a: std.meta.Vector(a_len, E)",
-            "b: std.meta.Vector(b_len, E)",
-            "comptime mask: std.meta.Vector(mask_len, i32)",
+            "a: @Vector(a_len, E)",
+            "b: @Vector(b_len, E)",
+            "comptime mask: @Vector(mask_len, i32)",
         },
     },
     .{
@@ -1398,17 +1401,12 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@splat",
-        .signature = "@splat(comptime len: u32, scalar: anytype) std.meta.Vector(len, @TypeOf(scalar))",
+        .signature = "@splat(comptime len: u32, scalar: anytype) @Vector(len, @TypeOf(scalar))",
         .snippet = "@splat(${1:comptime len: u32}, ${2:scalar: anytype})",
         .documentation =
-        \\Produces a vector of length `len` where each element is the value `scalar`:</p> {#code_begin|test|vector_splat#} const std = @import("std"); const expect = std.testing.expect; test "vector @splat" { const scalar: u32 = 5; const result = @splat(4, scalar); comptime try expect(@TypeOf(result) == std.meta.Vector(4, u32)); try expect(std.mem.eql(u32, &@as([4]u32, result), &[_]u32{ 5, 5, 5, 5 })); }`<pre>
-        \\      
+        \\Produces a vector of length `len` where each element is the value `scalar`:</p> {#code_begin|test|vector_splat#} const std = @import("std"); const expect = std.testing.expect; test "vector @splat" { const scalar: u32 = 5; const result = @splat(4, scalar); comptime try expect(@TypeOf(result) == @Vector(4, u32)); try expect(std.mem.eql(u32, &@as([4]u32, result), &[_]u32{ 5, 5, 5, 5 })); }` 
         \\
-        \\
-        \\      `scalar` must be an [integer](https://ziglang.org/documentation/master/#Integers), [bool](https://ziglang.org/documentation/master/#Primitive-Types),
-        \\      [float](https://ziglang.org/documentation/master/#Floats), or [pointer](https://ziglang.org/documentation/master/#Pointers).
-        \\      </p>
-        \\      
+        \\`scalar` must be an [integer](https://ziglang.org/documentation/master/#Integers), [bool](https://ziglang.org/documentation/master/#Primitive-Types), [float](https://ziglang.org/documentation/master/#Floats), or [pointer](https://ziglang.org/documentation/master/#Pointers).
         ,
         .arguments = &.{
             "comptime len: u32",
@@ -1417,18 +1415,17 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@reduce",
-        .signature = "@reduce(comptime op: std.builtin.ReduceOp, value: anytype) std.meta.Child(value)",
+        .signature = "@reduce(comptime op: std.builtin.ReduceOp, value: anytype) E",
         .snippet = "@reduce(${1:comptime op: std.builtin.ReduceOp}, ${2:value: anytype})",
         .documentation =
-        \\Transforms a [vector](https://ziglang.org/documentation/master/#Vectors) into a scalar value by performing a sequential horizontal reduction of its elements using the specified operator `op`.
+        \\Transforms a [vector](https://ziglang.org/documentation/master/#Vectors) into a scalar value (of type `E`) by performing a sequential horizontal reduction of its elements using the specified operator `op`.
         \\
         \\Not every operator is available for every vector element type:
-        \\  - `.And`, `.Or`, `.Xor` are available for `bool` vectors,
-        \\  - `.Min`, `.Max`, `.Add`, `.Mul` are available for [floating point](https://ziglang.org/documentation/master/#Floats) vectors,
         \\  - Every operator is available for [integer](https://ziglang.org/documentation/master/#Integers) vectors.
+        \\  - `.And`, `.Or`, `.Xor` are additionally available for `bool` vectors,
+        \\  - `.Min`, `.Max`, `.Add`, `.Mul` are additionally available for [floating point](https://ziglang.org/documentation/master/#Floats) vectors,
         \\
-        \\Note that `.Add` and `.Mul` reductions on integral types are wrapping; when applied on floating point types the operation associativity is preserved, unless the float mode is set to `Optimized`.</p> {#code_begin|test|vector_reduce#} const std = @import("std"); const expect = std.testing.expect; test "vector @reduce" { const value: std.meta.Vector(4, i32) = [_]i32{ 1, -1, 1, -1 }; const result = value > @splat(4, @as(i32, 0)); // result is { true, false, true, false }; comptime try expect(@TypeOf(result) == std.meta.Vector(4, bool)); const is_all_true = @reduce(.And, result); comptime try expect(@TypeOf(is_all_true) == bool); try expect(is_all_true == false); }`<pre>
-        \\      
+        \\Note that `.Add` and `.Mul` reductions on integral types are wrapping; when applied on floating point types the operation associativity is preserved, unless the float mode is set to `Optimized`.</p> {#code_begin|test|vector_reduce#} const std = @import("std"); const expect = std.testing.expect; test "vector @reduce" { const value = @Vector(4, i32){ 1, -1, 1, -1 }; const result = value > @splat(4, @as(i32, 0)); // result is { true, false, true, false }; comptime try expect(@TypeOf(result) == @Vector(4, bool)); const is_all_true = @reduce(.And, result); comptime try expect(@TypeOf(is_all_true) == bool); try expect(is_all_true == false); }`
         ,
         .arguments = &.{
             "comptime op: std.builtin.ReduceOp",
@@ -1440,7 +1437,7 @@ pub const builtins = [_]Builtin{
         .signature = "@src() std.builtin.SourceLocation",
         .snippet = "@src()",
         .documentation =
-        \\Returns a `SourceLocation` struct representing the function's name and location in the source code. This must be called in a function.</p> {#code_begin|test|source_location#} const std = @import("std"); const expect = std.testing.expect; test "@src" { try doTheTest(); } fn doTheTest() !void { const src = @src(); try expect(src.line == 9); try expect(src.column == 17); try expect(std.mem.endsWith(u8, src.fn_name, "doTheTest")); try expect(std.mem.endsWith(u8, src.file, "source_location.zig")); }`<pre>
+        \\Returns a `SourceLocation` struct representing the function's name and location in the source code. This must be called in a function.</p> {#code_begin|test|source_location#} const std = @import("std"); const expect = std.testing.expect; test "@src" { try doTheTest(); } fn doTheTest() !void { const src = @src(); try expect(src.line == 9); try expect(src.column == 17); try expect(std.mem.endsWith(u8, src.fn_name, "doTheTest")); try expect(std.mem.endsWith(u8, src.file, "source_location.zig")); }`
         ,
         .arguments = &.{},
     },
@@ -1483,6 +1480,19 @@ pub const builtins = [_]Builtin{
             "value: anytype",
         },
     },
+    .{
+        .name = "@tan",
+        .signature = "@tan(value: anytype) @TypeOf(value)",
+        .snippet = "@tan(${1:value: anytype})",
+        .documentation =
+        \\Tangent trigonometric function on a floating point number. Uses a dedicated hardware instruction when available.
+        \\
+        \\Supports [Floats](https://ziglang.org/documentation/master/#Floats) and [Vectors](https://ziglang.org/documentation/master/#Vectors) of floats, with the caveat that [some float operations are not yet implemented for all float types](https://github.com/ziglang/zig/issues/4026).
+        ,
+        .arguments = &.{
+            "value: anytype",
+        },
+    },
     .{
         .name = "@exp",
         .signature = "@exp(value: anytype) @TypeOf(value)",
@@ -1645,13 +1655,9 @@ pub const builtins = [_]Builtin{
         .signature = "@This() type",
         .snippet = "@This()",
         .documentation =
-        \\Returns the innermost struct, enum, or union that this function call is inside. This can be useful for an anonymous struct that needs to refer to itself:</p> {#code_begin|test|this_innermost#} const std = @import("std"); const expect = std.testing.expect; test "@This()" { var items = [_]i32{ 1, 2, 3, 4 }; const list = List(i32){ .items = items[0..] }; try expect(list.length() == 4); } fn List(comptime T: type) type { return struct { const Self = @This(); items: []T, fn length(self: Self) usize { return self.items.len; } }; }`<pre>
-        \\      
+        \\Returns the innermost struct, enum, or union that this function call is inside. This can be useful for an anonymous struct that needs to refer to itself:</p> {#code_begin|test|this_innermost#} const std = @import("std"); const expect = std.testing.expect; test "@This()" { var items = [_]i32{ 1, 2, 3, 4 }; const list = List(i32){ .items = items[0..] }; try expect(list.length() == 4); } fn List(comptime T: type) type { return struct { const Self = @This(); items: []T, fn length(self: Self) usize { return self.items.len; } }; }` 
         \\
-        \\
-        \\      When `@This()` is used at file scope, it returns a reference to the
-        \\      struct that corresponds to the current file.
-        \\      
+        \\When `@This()` is used at file scope, it returns a reference to the struct that corresponds to the current file.
         ,
         .arguments = &.{},
     },
@@ -1662,17 +1668,9 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\This function truncates bits from an integer type, resulting in a smaller or same-sized integer type.
         \\
-        \\The following produces safety-checked [Undefined Behavior](https://ziglang.org/documentation/master/#Undefined-Behavior):
+        \\This function always truncates the significant bits of the integer, regardless of endianness on the target platform.
         \\
-        \\```zig
-        \\test "integer cast panic" {
-        \\    var a: u16 = 0xabcd;
-        \\    var b: u8 = @intCast(u8, a);
-        \\    _ = b;
-        \\}
-        \\```
-        \\
-        \\However this is well defined and working code:
+        \\Calling `@truncate` on a number out of range of the destination type is well defined and working code:
         \\
         \\```zig
         \\const std = @import("std");
@@ -1685,7 +1683,7 @@ pub const builtins = [_]Builtin{
         \\}
         \\```
         \\
-        \\This function always truncates the significant bits of the integer, regardless of endianness on the target platform.
+        \\Use [@intCast](https://ziglang.org/documentation/master/#intCast) to convert numbers guaranteed to fit the destination type.
         ,
         .arguments = &.{
             "comptime T: type",
@@ -1694,8 +1692,8 @@ pub const builtins = [_]Builtin{
     },
     .{
         .name = "@Type",
-        .signature = "@Type(comptime info: std.builtin.TypeInfo) type",
-        .snippet = "@Type(${1:comptime info: std.builtin.TypeInfo})",
+        .signature = "@Type(comptime info: std.builtin.Type) type",
+        .snippet = "@Type(${1:comptime info: std.builtin.Type})",
         .documentation =
         \\This function is the inverse of [@typeInfo](https://ziglang.org/documentation/master/#typeInfo). It reifies type information into a `type`.
         \\
@@ -1729,17 +1727,19 @@ pub const builtins = [_]Builtin{
         \\  - BoundFn
         ,
         .arguments = &.{
-            "comptime info: std.builtin.TypeInfo",
+            "comptime info: std.builtin.Type",
         },
     },
     .{
         .name = "@typeInfo",
-        .signature = "@typeInfo(comptime T: type) std.builtin.TypeInfo",
+        .signature = "@typeInfo(comptime T: type) std.builtin.Type",
         .snippet = "@typeInfo(${1:comptime T: type})",
         .documentation =
         \\Provides type reflection.
         \\
-        \\For [structs](https://ziglang.org/documentation/master/#struct), [unions](https://ziglang.org/documentation/master/#union), [enums](https://ziglang.org/documentation/master/#enum), and [error sets](https://ziglang.org/documentation/master/#Error-Set-Type), the fields are guaranteed to be in the same order as declared. For declarations, the order is unspecified.
+        \\Type information of [structs](https://ziglang.org/documentation/master/#struct), [unions](https://ziglang.org/documentation/master/#union), [enums](https://ziglang.org/documentation/master/#enum), and [error sets](https://ziglang.org/documentation/master/#Error-Set-Type) has fields which are are guaranteed to be in the same order as appearance in the source file.
+        \\
+        \\Type information of [structs](https://ziglang.org/documentation/master/#struct), [unions](https://ziglang.org/documentation/master/#union), [enums](https://ziglang.org/documentation/master/#enum), and [opaques](https://ziglang.org/documentation/master/#opaque) has declarations, which are also guaranteed to be in the same order as appearance in the source file.
         ,
         .arguments = &.{
             "comptime T: type",
@@ -1750,7 +1750,7 @@ pub const builtins = [_]Builtin{
         .signature = "@typeName(T: type) *const [N:0]u8",
         .snippet = "@typeName(${1:T: type})",
         .documentation =
-        \\This function returns the string representation of a type, as an array. It is equivalent to a string literal of the type name.
+        \\This function returns the string representation of a type, as an array. It is equivalent to a string literal of the type name. The returned type name is fully qualified with the parent namespace included as part of the type name with a series of dots.
         ,
         .arguments = &.{
             "T: type",
@@ -1763,7 +1763,7 @@ pub const builtins = [_]Builtin{
         .documentation =
         \\`@TypeOf` is a special builtin function that takes any (nonzero) number of expressions as parameters and returns the type of the result, using [Peer Type Resolution](https://ziglang.org/documentation/master/#Peer-Type-Resolution).
         \\
-        \\The expressions are evaluated, however they are guaranteed to have no *runtime* side-effects:</p> {#code_begin|test|no_runtime_side_effects#} const std = @import("std"); const expect = std.testing.expect; test "no runtime side effects" { var data: i32 = 0; const T = @TypeOf(foo(i32, &data)); comptime try expect(T == i32); try expect(data == 0); } fn foo(comptime T: type, ptr: *T) T { ptr.* += 1; return ptr.*; }`<pre>
+        \\The expressions are evaluated, however they are guaranteed to have no *runtime* side-effects:</p> {#code_begin|test|no_runtime_side_effects#} const std = @import("std"); const expect = std.testing.expect; test "no runtime side effects" { var data: i32 = 0; const T = @TypeOf(foo(i32, &data)); comptime try expect(T == i32); try expect(data == 0); } fn foo(comptime T: type, ptr: *T) T { ptr.* += 1; return ptr.*; }`
         ,
         .arguments = &.{
             "...",
@@ -1784,4 +1784,16 @@ pub const builtins = [_]Builtin{
             "init_expr",
         },
     },
+    .{
+        .name = "@Vector",
+        .signature = "@Vector(len: comptime_int, Element: type) type",
+        .snippet = "@Vector(${1:len: comptime_int}, ${2:Element: type})",
+        .documentation =
+        \\Creates [Vectors](https://ziglang.org/documentation/master/#Vectors).
+        ,
+        .arguments = &.{
+            "len: comptime_int",
+            "Element: type",
+        },
+    },
 };