Commit ce7c66e2d0ccaf0265f2c2afce9824c9b9ae6123 | zig

author	Andrew Kelley <andrew@ziglang.org> 2024-01-21 20:39:50-07:00
committer	Andrew Kelley <andrew@ziglang.org> 2024-01-21 20:39:50-07:00
log	ce7c66e2d0ccaf0265f2c2afce9824c9b9ae6123
tree	8428815a61dac26778872cc588713593335b4bea
parent	1b8e6b8ba9c6a0f52e2d823218732bb2dc8a0362

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
lib
- std
  - builtin.zig

doc/langref.html.in+15-64

 @@ -7754,7 +7754,7 @@ comptime {
       {#header_close#}
       {#header_open|@atomicLoad#}
-      <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
+      <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
       <p>
       This builtin function atomically dereferences a pointer to a {#syntax#}T{#endsyntax#} and returns the value.
       </p>
 @@ -7762,11 +7762,12 @@ comptime {
       {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
       an integer or an enum.
       </p>
+      <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
       {#see_also|@atomicStore|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
       {#header_close#}
       {#header_open|@atomicRmw#}
-      <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
+      <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
       <p>
       This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically
       modifies the value and returns the previous value.
 @@ -7775,27 +7776,13 @@ comptime {
       {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
       an integer or an enum.
       </p>
-      <p>
+      <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
-      Supported values for the {#syntax#}op{#endsyntax#} parameter:
+      <p>{#syntax#}AtomicRmwOp{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicRmwOp{#endsyntax#}.</p>
-      </p>
-      <ul>
-        <li>{#syntax#}.Xchg{#endsyntax#} - stores the operand unmodified. Supports enums, integers and floats.</li>
-        <li>{#syntax#}.Add{#endsyntax#} - for integers, twos complement wraparound addition.
-            Also supports {#link|Floats#}.</li>
-        <li>{#syntax#}.Sub{#endsyntax#} - for integers, twos complement wraparound subtraction.
-            Also supports {#link|Floats#}.</li>
-        <li>{#syntax#}.And{#endsyntax#} - bitwise and</li>
-        <li>{#syntax#}.Nand{#endsyntax#} - bitwise nand</li>
-        <li>{#syntax#}.Or{#endsyntax#} - bitwise or</li>
-        <li>{#syntax#}.Xor{#endsyntax#} - bitwise xor</li>
-        <li>{#syntax#}.Max{#endsyntax#} - stores the operand if it is larger. Supports integers and floats.</li>
-        <li>{#syntax#}.Min{#endsyntax#} - stores the operand if it is smaller. Supports integers and floats.</li>
-      </ul>
       {#see_also|@atomicStore|@atomicLoad|@fence|@cmpxchgWeak|@cmpxchgStrong#}
       {#header_close#}
       {#header_open|@atomicStore#}
-      <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: builtin.AtomicOrder) void{#endsyntax#}</pre>
+      <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void{#endsyntax#}</pre>
       <p>
       This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically stores the given value.
       </p>
 @@ -7803,6 +7790,7 @@ comptime {
       {#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
       an integer or an enum.
       </p>
+      <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
       {#see_also|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
       {#header_close#}
 @@ -8079,6 +8067,7 @@ fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_v
       an integer or an enum.
       </p>
       <p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
+      <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
       {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak#}
       {#header_close#}
 @@ -8110,6 +8099,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       an integer or an enum.
       </p>
       <p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
+      <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
       {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgStrong#}
       {#header_close#}
 @@ -8400,9 +8390,7 @@ export fn @"A function name that is a complete sentence."() void {}
       <p>
       The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.
       </p>
-      <p>
+      <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
-      {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.
-      </p>
       {#see_also|@atomicStore|@atomicLoad|@atomicRmw|@cmpxchgWeak|@cmpxchgStrong#}
       {#header_close#}
 @@ -8810,7 +8798,7 @@ test "@wasmMemoryGrow" {
       {#header_close#}
       {#header_open|@prefetch#}
-      <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: std.builtin.PrefetchOptions) void{#endsyntax#}</pre>
+      <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: PrefetchOptions) void{#endsyntax#}</pre>
       <p>
       This builtin tells the compiler to emit a prefetch instruction if supported by the
       target CPU. If the target CPU does not support the requested prefetch instruction,
 @@ -8822,37 +8810,7 @@ test "@wasmMemoryGrow" {
       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.
       </p>
-      <p>
+      <p>{#syntax#}PrefetchOptions{#endsyntax#} can be found with {#syntax#}@import("std").builtin.PrefetchOptions{#endsyntax#}.</p>
-      The {#syntax#}options{#endsyntax#} 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,
-    /// The data's locality in an inclusive range from 0 to 3.
-    ///
-    /// 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(u1) {
-        read,
-        write,
-    };
-    pub const Cache = enum(u1) {
-        instruction,
-        data,
-    };
-};
-      {#code_end#}
       {#header_close#}
       {#header_open|@ptrCast#}
 @@ -8981,16 +8939,8 @@ test "foo" {
       {#header_close#}
       {#header_open|@setFloatMode#}
-      <pre>{#syntax#}@setFloatMode(comptime mode: @import("std").builtin.FloatMode) void{#endsyntax#}</pre>
+      <pre>{#syntax#}@setFloatMode(comptime mode: FloatMode) void{#endsyntax#}</pre>
-      <p>
+      <p>Changes the current scope's rules about how floating point operations are defined.</p>
-      Sets the floating point mode of the current scope. Possible values are:
-      </p>
-      {#code_begin|syntax|FloatMode#}
-pub const FloatMode = enum {
-    Strict,
-    Optimized,
-};
-      {#code_end#}
       <ul>
         <li>
             {#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance.
 @@ -9012,6 +8962,7 @@ pub const FloatMode = enum {
       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.
       </p>
+      <p>{#syntax#}FloatMode{#endsyntax#} can be found with {#syntax#}@import("std").builtin.FloatMode{#endsyntax#}.</p>
       {#see_also|Floating Point Operations#}
       {#header_close#}

lib/std/builtin.zig+20

...	@@ -102,14 +102,34 @@ pub const ReduceOp = enum {	...	@@ -102,14 +102,34 @@ pub const ReduceOp = enum {
102	/// This data structure is used by the Zig language code generation and	102	/// This data structure is used by the Zig language code generation and
103	/// therefore must be kept in sync with the compiler implementation.	103	/// therefore must be kept in sync with the compiler implementation.
104	pub const AtomicRmwOp = enum {	104	pub const AtomicRmwOp = enum {
		105	/// Exchange - store the operand unmodified.
		106	/// Supports enums, integers, and floats.
105	Xchg,	107	Xchg,
		108	/// Add operand to existing value.
		109	/// Supports integers and floats.
		110	/// For integers, two's complement wraparound applies.
106	Add,	111	Add,
		112	/// Subtract operand from existing value.
		113	/// Supports integers and floats.
		114	/// For integers, two's complement wraparound applies.
107	Sub,	115	Sub,
		116	/// Perform bitwise AND on existing value with operand.
		117	/// Supports integers.
108	And,	118	And,
		119	/// Perform bitwise NAND on existing value with operand.
		120	/// Supports integers.
109	Nand,	121	Nand,
		122	/// Perform bitwise OR on existing value with operand.
		123	/// Supports integers.
110	Or,	124	Or,
		125	/// Perform bitwise XOR on existing value with operand.
		126	/// Supports integers.
111	Xor,	127	Xor,
		128	/// Store operand if it is larger than the existing value.
		129	/// Supports integers and floats.
112	Max,	130	Max,
		131	/// Store operand if it is smaller than the existing value.
		132	/// Supports integers and floats.
113	Min,	133	Min,
114	};	134	};
115		135