langref corrections and clarifications

doc/langref.html.in

@@ -773,9 +773,9 @@
 
       <p>
       {#syntax#}undefined{#endsyntax#} can be {#link|coerced|Type Coercion#} to any type.
-          Once this happens, it is no longer possible to detect that the value is {#syntax#}undefined{#endsyntax#}.
-              {#syntax#}undefined{#endsyntax#} means the value could be anything, even something that is nonsense
-                  according to the type. Translated into English, {#syntax#}undefined{#endsyntax#} means "Not a meaningful
+      Once this happens, it is no longer possible to detect that the value is {#syntax#}undefined{#endsyntax#}.
+      {#syntax#}undefined{#endsyntax#} means the value could be anything, even something that is nonsense
+      according to the type. Translated into English, {#syntax#}undefined{#endsyntax#} means "Not a meaningful
       value. Using this value would be a bug. The value will be unused, or overwritten before being used."
       </p>
       <p>
@@ -5393,9 +5393,9 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       <pre>{#syntax#}@shlExact(value: T, shift_amt: Log2T) T{#endsyntax#}</pre>
       <p>
       Performs the left shift operation ({#syntax#}<<{#endsyntax#}).
-      For unsigned integers, the result is {#link|undefined#} if any 1 bits
-      are shifted out. For signed integers, the result is {#link|undefined#} if
-      any bits that disagree with the resultant sign bit are shifted out.
+      For unsigned integers, shifting out any 1 bits results in safety-checked
+      {#link|Illegal Behavior#}. For signed integers, shifting out any bits
+      that disagree with the resultant sign bit results in safety-checked {#link|Illegal Behavior#}.
       </p>
       <p>
       The type of {#syntax#}shift_amt{#endsyntax#} is an unsigned integer with {#syntax#}log2(@typeInfo(T).int.bits){#endsyntax#} bits.
@@ -5424,8 +5424,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       {#header_open|@shrExact#}
       <pre>{#syntax#}@shrExact(value: T, shift_amt: Log2T) T{#endsyntax#}</pre>
       <p>
-      Performs the right shift operation ({#syntax#}>>{#endsyntax#}). Caller guarantees
-      that the shift will not shift any 1 bits out.
+      Performs the right shift operation ({#syntax#}>>{#endsyntax#}).
+      Shifting out any 1 bits results in safety-checked {#link|Illegal Behavior#}.
       </p>
       <p>
       The type of {#syntax#}shift_amt{#endsyntax#} is an unsigned integer with {#syntax#}log2(@typeInfo(T).int.bits){#endsyntax#} bits.
@@ -5712,7 +5712,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       {#header_open|@This#}
       <pre>{#syntax#}@This() type{#endsyntax#}</pre>
       <p>
-      Returns the innermost struct, enum, or union that this function call is inside.
+      Returns the innermost non-tuple 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|test_this_builtin.zig#}

doc/langref/float_mode_exe.zig

@@ -1,12 +1,12 @@
 const print = @import("std").debug.print;
 
-extern fn foo_strict(x: f64) f64;
-extern fn foo_optimized(x: f64) f64;
+extern fn fooStrict(x: f64) f64;
+extern fn fooOptimized(x: f64) f64;
 
 pub fn main() void {
     const x = 0.001;
-    print("optimized = {}\n", .{foo_optimized(x)});
-    print("strict = {}\n", .{foo_strict(x)});
+    print("optimized = {}\n", .{fooOptimized(x)});
+    print("strict = {}\n", .{fooStrict(x)});
 }
 
 // syntax

doc/langref/float_mode_obj.zig

@@ -1,11 +1,11 @@
 const std = @import("std");
 const big = @as(f64, 1 << 40);
 
-export fn foo_strict(x: f64) f64 {
+export fn fooStrict(x: f64) f64 {
     return x + big - big;
 }
 
-export fn foo_optimized(x: f64) f64 {
+export fn fooOptimized(x: f64) f64 {
     @setFloatMode(.optimized);
     return x + big - big;
 }

doc/langref/test_comptime_shrExact_overflow.zig

@@ -3,4 +3,4 @@ comptime {
     _ = x;
 }
 
-// test_error=exact shift shifted out 1 bits
+// test_error=exact right shift shifted out 1 bits

lib/std/Random.zig

@@ -224,7 +224,7 @@ pub fn intRangeLessThan(r: Random, comptime T: type, at_least: T, less_than: T)
     }
 }
 
-/// Constant-time implementation off `intRangeAtMostBiased`.
+/// Constant-time implementation off `intRangeAtMost`.
 /// The results of this function may be biased.
 pub fn intRangeAtMostBiased(r: Random, comptime T: type, at_least: T, at_most: T) T {
     assert(at_least <= at_most);

lib/std/builtin.zig

@@ -738,6 +738,7 @@ pub const Type = union(enum) {
 
     /// This data structure is used by the Zig language code generation and
     /// therefore must be kept in sync with the compiler implementation.
+    /// `null` is the set of all errors (`@typeInfo(anyerror).error_set`).
     pub const ErrorSet = ?[]const Error;
 
     /// This data structure is used by the Zig language code generation and

lib/std/debug.zig

@@ -152,11 +152,11 @@ pub fn FullPanic(comptime panicFn: fn ([]const u8, ?usize) noreturn) type {
         }
         pub fn shlOverflow() noreturn {
             @branchHint(.cold);
-            call("left shift overflowed bits", @returnAddress());
+            call("exact left shift overflowed bits", @returnAddress());
         }
         pub fn shrOverflow() noreturn {
             @branchHint(.cold);
-            call("right shift overflowed bits", @returnAddress());
+            call("exact right shift shifted out 1 bits", @returnAddress());
         }
         pub fn divideByZero() noreturn {
             @branchHint(.cold);

lib/std/debug/simple_panic.zig

@@ -81,11 +81,11 @@ pub fn integerOverflow() noreturn {
 }
 
 pub fn shlOverflow() noreturn {
-    call("left shift overflowed bits", null);
+    call("exact left shift overflowed bits", null);
 }
 
 pub fn shrOverflow() noreturn {
-    call("right shift overflowed bits", null);
+    call("exact right shift shifted out 1 bits", null);
 }
 
 pub fn divideByZero() noreturn {

src/Sema/arith.zig

@@ -1978,7 +1978,7 @@ fn intShr(
     }
     if (op == .shr_exact and lhs_bigint.ctz(shift_amt) < shift_amt) {
         return sema.failWithOwnedErrorMsg(block, msg: {
-            const msg = try sema.errMsg(src, "exact shift shifted out 1 bits", .{});
+            const msg = try sema.errMsg(src, "exact right shift shifted out 1 bits", .{});
             errdefer msg.destroy(sema.gpa);
             if (vec_idx) |i| try sema.errNote(rhs_src, msg, "when computing vector element at index '{d}'", .{i});
             break :msg msg;

test/cases/compile_errors/shrExact_shifts_out_1_bits.zig

@@ -5,4 +5,4 @@ comptime {
 
 // error
 //
-// :2:15: error: exact shift shifted out 1 bits
+// :2:15: error: exact right shift shifted out 1 bits

test/cases/safety/signed shift left overflow.zig

@@ -2,7 +2,7 @@ const std = @import("std");
 
 pub fn panic(message: []const u8, stack_trace: ?*std.builtin.StackTrace, _: ?usize) noreturn {
     _ = stack_trace;
-    if (std.mem.eql(u8, message, "left shift overflowed bits")) {
+    if (std.mem.eql(u8, message, "exact left shift overflowed bits")) {
         std.process.exit(0);
     }
     std.process.exit(1);

test/cases/safety/signed shift right overflow.zig

@@ -2,7 +2,7 @@ const std = @import("std");
 
 pub fn panic(message: []const u8, stack_trace: ?*std.builtin.StackTrace, _: ?usize) noreturn {
     _ = stack_trace;
-    if (std.mem.eql(u8, message, "right shift overflowed bits")) {
+    if (std.mem.eql(u8, message, "exact right shift shifted out 1 bits")) {
         std.process.exit(0);
     }
     std.process.exit(1);

test/cases/safety/unsigned shift left overflow.zig

@@ -2,7 +2,7 @@ const std = @import("std");
 
 pub fn panic(message: []const u8, stack_trace: ?*std.builtin.StackTrace, _: ?usize) noreturn {
     _ = stack_trace;
-    if (std.mem.eql(u8, message, "left shift overflowed bits")) {
+    if (std.mem.eql(u8, message, "exact left shift overflowed bits")) {
         std.process.exit(0);
     }
     std.process.exit(1);

test/cases/safety/unsigned shift right overflow.zig

@@ -2,7 +2,7 @@ const std = @import("std");
 
 pub fn panic(message: []const u8, stack_trace: ?*std.builtin.StackTrace, _: ?usize) noreturn {
     _ = stack_trace;
-    if (std.mem.eql(u8, message, "right shift overflowed bits")) {
+    if (std.mem.eql(u8, message, "exact right shift shifted out 1 bits")) {
         std.process.exit(0);
     }
     std.process.exit(1);