authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-21 20:39:50-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-21 20:39:50-07:00
logce7c66e2d0ccaf0265f2c2afce9824c9b9ae6123
tree8428815a61dac26778872cc588713593335b4bea
parent1b8e6b8ba9c6a0f52e2d823218732bb2dc8a0362

langref: make more consistent

* moves some langref into std.builtin doc comments * use the same way of referencing stuff from std.builtin closes #16483

2 files changed, 35 insertions(+), 64 deletions(-)

doc/langref.html.in+15-64
......@@ -7754,7 +7754,7 @@ comptime {
77547754 {#header_close#}
77557755
77567756 {#header_open|@atomicLoad#}
7757 <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
7757 <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
77587758 <p>
77597759 This builtin function atomically dereferences a pointer to a {#syntax#}T{#endsyntax#} and returns the value.
77607760 </p>
......@@ -7762,11 +7762,12 @@ comptime {
77627762 {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
77637763 an integer or an enum.
77647764 </p>
7765 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
77657766 {#see_also|@atomicStore|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
77667767 {#header_close#}
77677768
77687769 {#header_open|@atomicRmw#}
7769 <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
7770 <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
77707771 <p>
77717772 This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically
77727773 modifies the value and returns the previous value.
......@@ -7775,27 +7776,13 @@ comptime {
77757776 {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
77767777 an integer or an enum.
77777778 </p>
7778 <p>
7779 Supported values for the {#syntax#}op{#endsyntax#} parameter:
7780 </p>
7781 <ul>
7782 <li>{#syntax#}.Xchg{#endsyntax#} - stores the operand unmodified. Supports enums, integers and floats.</li>
7783 <li>{#syntax#}.Add{#endsyntax#} - for integers, twos complement wraparound addition.
7784 Also supports {#link|Floats#}.</li>
7785 <li>{#syntax#}.Sub{#endsyntax#} - for integers, twos complement wraparound subtraction.
7786 Also supports {#link|Floats#}.</li>
7787 <li>{#syntax#}.And{#endsyntax#} - bitwise and</li>
7788 <li>{#syntax#}.Nand{#endsyntax#} - bitwise nand</li>
7789 <li>{#syntax#}.Or{#endsyntax#} - bitwise or</li>
7790 <li>{#syntax#}.Xor{#endsyntax#} - bitwise xor</li>
7791 <li>{#syntax#}.Max{#endsyntax#} - stores the operand if it is larger. Supports integers and floats.</li>
7792 <li>{#syntax#}.Min{#endsyntax#} - stores the operand if it is smaller. Supports integers and floats.</li>
7793 </ul>
7779 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
7780 <p>{#syntax#}AtomicRmwOp{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicRmwOp{#endsyntax#}.</p>
77947781 {#see_also|@atomicStore|@atomicLoad|@fence|@cmpxchgWeak|@cmpxchgStrong#}
77957782 {#header_close#}
77967783
77977784 {#header_open|@atomicStore#}
7798 <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: builtin.AtomicOrder) void{#endsyntax#}</pre>
7785 <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void{#endsyntax#}</pre>
77997786 <p>
78007787 This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically stores the given value.
78017788 </p>
......@@ -7803,6 +7790,7 @@ comptime {
78037790 {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
78047791 an integer or an enum.
78057792 </p>
7793 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
78067794 {#see_also|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
78077795 {#header_close#}
78087796
......@@ -8079,6 +8067,7 @@ fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_v
80798067 an integer or an enum.
80808068 </p>
80818069 <p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
8070 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
80828071 {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak#}
80838072 {#header_close#}
80848073
......@@ -8110,6 +8099,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
81108099 an integer or an enum.
81118100 </p>
81128101 <p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
8102 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
81138103 {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgStrong#}
81148104 {#header_close#}
81158105
......@@ -8400,9 +8390,7 @@ export fn @"A function name that is a complete sentence."() void {}
84008390 <p>
84018391 The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.
84028392 </p>
8403 <p>
8404 {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.
8405 </p>
8393 <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
84068394 {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@cmpxchgWeak|@cmpxchgStrong#}
84078395 {#header_close#}
84088396
......@@ -8810,7 +8798,7 @@ test "@wasmMemoryGrow" {
88108798 {#header_close#}
88118799
88128800 {#header_open|@prefetch#}
8813 <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: std.builtin.PrefetchOptions) void{#endsyntax#}</pre>
8801 <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: PrefetchOptions) void{#endsyntax#}</pre>
88148802 <p>
88158803 This builtin tells the compiler to emit a prefetch instruction if supported by the
88168804 target CPU. If the target CPU does not support the requested prefetch instruction,
......@@ -8822,37 +8810,7 @@ test "@wasmMemoryGrow" {
88228810 address to prefetch. This function does not dereference the pointer, it is perfectly legal
88238811 to pass a pointer to invalid memory to this function and no illegal behavior will result.
88248812 </p>
8825 <p>
8826 The {#syntax#}options{#endsyntax#} argument is the following struct:
8827 </p>
8828 {#code_begin|syntax|builtin#}
8829/// This data structure is used by the Zig language code generation and
8830/// therefore must be kept in sync with the compiler implementation.
8831pub const PrefetchOptions = struct {
8832 /// Whether the prefetch should prepare for a read or a write.
8833 rw: Rw = .read,
8834 /// The data's locality in an inclusive range from 0 to 3.
8835 ///
8836 /// 0 means no temporal locality. That is, the data can be immediately
8837 /// dropped from the cache after it is accessed.
8838 ///
8839 /// 3 means high temporal locality. That is, the data should be kept in
8840 /// the cache as it is likely to be accessed again soon.
8841 locality: u2 = 3,
8842 /// The cache that the prefetch should be preformed on.
8843 cache: Cache = .data,
8844
8845 pub const Rw = enum(u1) {
8846 read,
8847 write,
8848 };
8849
8850 pub const Cache = enum(u1) {
8851 instruction,
8852 data,
8853 };
8854};
8855 {#code_end#}
8813 <p>{#syntax#}PrefetchOptions{#endsyntax#} can be found with {#syntax#}@import("std").builtin.PrefetchOptions{#endsyntax#}.</p>
88568814 {#header_close#}
88578815
88588816 {#header_open|@ptrCast#}
......@@ -8981,16 +8939,8 @@ test "foo" {
89818939 {#header_close#}
89828940
89838941 {#header_open|@setFloatMode#}
8984 <pre>{#syntax#}@setFloatMode(comptime mode: @import("std").builtin.FloatMode) void{#endsyntax#}</pre>
8985 <p>
8986 Sets the floating point mode of the current scope. Possible values are:
8987 </p>
8988 {#code_begin|syntax|FloatMode#}
8989pub const FloatMode = enum {
8990 Strict,
8991 Optimized,
8992};
8993 {#code_end#}
8942 <pre>{#syntax#}@setFloatMode(comptime mode: FloatMode) void{#endsyntax#}</pre>
8943 <p>Changes the current scope's rules about how floating point operations are defined.</p>
89948944 <ul>
89958945 <li>
89968946 {#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance.
......@@ -9012,6 +8962,7 @@ pub const FloatMode = enum {
90128962 The floating point mode is inherited by child scopes, and can be overridden in any scope.
90138963 You can set the floating point mode in a struct or module scope by using a comptime block.
90148964 </p>
8965 <p>{#syntax#}FloatMode{#endsyntax#} can be found with {#syntax#}@import("std").builtin.FloatMode{#endsyntax#}.</p>
90158966 {#see_also|Floating Point Operations#}
90168967 {#header_close#}
90178968
lib/std/builtin.zig+20
......@@ -102,14 +102,34 @@ pub const ReduceOp = enum {
102102/// This data structure is used by the Zig language code generation and
103103/// therefore must be kept in sync with the compiler implementation.
104104pub const AtomicRmwOp = enum {
105 /// Exchange - store the operand unmodified.
106 /// Supports enums, integers, and floats.
105107 Xchg,
108 /// Add operand to existing value.
109 /// Supports integers and floats.
110 /// For integers, two's complement wraparound applies.
106111 Add,
112 /// Subtract operand from existing value.
113 /// Supports integers and floats.
114 /// For integers, two's complement wraparound applies.
107115 Sub,
116 /// Perform bitwise AND on existing value with operand.
117 /// Supports integers.
108118 And,
119 /// Perform bitwise NAND on existing value with operand.
120 /// Supports integers.
109121 Nand,
122 /// Perform bitwise OR on existing value with operand.
123 /// Supports integers.
110124 Or,
125 /// Perform bitwise XOR on existing value with operand.
126 /// Supports integers.
111127 Xor,
128 /// Store operand if it is larger than the existing value.
129 /// Supports integers and floats.
112130 Max,
131 /// Store operand if it is smaller than the existing value.
132 /// Supports integers and floats.
113133 Min,
114134};
115135