From bc8e1e1de4a2f22c56528240d320f682f1ec4b69 Mon Sep 17 00:00:00 2001
From: zooster <r00ster91@proton.me>
Date: Sun, 23 Apr 2023 20:06:21 +0200
Subject: [PATCH] Improvements to docs and text

* docs(std.math): elaborate on difference between absCast and absInt

* docs(std.rand.Random.weightedIndex): elaborate on likelihood

I think this makes it easier to understand.

* langref: add small reminder

* docs(std.fs.path.extension): brevity

* docs(std.bit_set.StaticBitSet): mention the specific types

* std.debug.TTY: explain what purpose this struct serves

This should also make it clearer that this struct is not supposed to provide unrelated terminal manipulation functionality such as setting the cursor position or something because terminals are complicated and we should keep this struct simple and focused on debugging.

* langref(package listing): brevity

* langref: explain what exactly `threadlocal` causes to happen

* std.array_list: link between swapRemove and orderedRemove

Maybe this can serve as a TLDR and make it easier to decide.

* PrefetchOptions.locality: clarify docs that this is a range

This confused me previously and I thought I can only use either 0 or 3.

* fix typos and more

* std.builtin.CallingConvention: document some CCs

* langref: explain possibly cryptic names

I think it helps knowing what exactly these acronyms (@clz and @ctz) and
abbreviations (@popCount) mean.

* variadic function error: add missing preposition

* std.fmt.format docs: nicely hyphenate

* help menu: say what to optimize for

I think this is slightly more specific than just calling it
"optimizations". These are speed optimizations. I used the word
"performance" here.
---
 doc/langref.html.in                           | 27 +++++++++++--------
 lib/std/Build/Cache.zig                       |  2 +-
 lib/std/RingBuffer.zig                        |  2 +-
 lib/std/Uri.zig                               |  2 +-
 lib/std/array_list.zig                        |  2 ++
 lib/std/bit_set.zig                           |  5 ++--
 lib/std/builtin.zig                           | 27 +++++++++++++++++++
 lib/std/compress/zstandard.zig                |  2 +-
 lib/std/compress/zstandard/decode/fse.zig     |  2 +-
 lib/std/debug.zig                             |  2 ++
 lib/std/fmt.zig                               |  2 +-
 lib/std/fs/path.zig                           |  7 +++--
 lib/std/macho.zig                             |  4 +--
 lib/std/math.zig                              |  7 ++---
 lib/std/mem.zig                               |  2 +-
 lib/std/os/linux/seccomp.zig                  |  2 +-
 lib/std/rand.zig                              |  2 ++
 src/Air.zig                                   |  2 +-
 src/Autodoc.zig                               |  4 +--
 src/Sema.zig                                  | 10 +++----
 src/link/NvPtx.zig                            |  2 +-
 src/main.zig                                  |  4 +--
 ...nion_init_with_none_or_multiple_fields.zig |  4 +--
 .../variadic_arg_validation.zig               |  2 +-
 24 files changed, 83 insertions(+), 44 deletions(-)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index a8af95961527c7a440463d22bd32e2712147c8ea..254f119d3d7dac144499652cb7b1e832edcdaa97 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -1422,7 +1422,8 @@ fn foo() i32 {
 
       {#header_open|Thread Local Variables#}
       <p>A variable may be specified to be a thread-local variable using the
-      {#syntax#}threadlocal{#endsyntax#} keyword:</p>
+      {#syntax#}threadlocal{#endsyntax#} keyword,
+      which makes each thread work with a separate instance of the variable:</p>
       {#code_begin|test|test_thread_local_variables#}
 const std = @import("std");
 const assert = std.debug.assert;
@@ -4278,7 +4279,7 @@ const expectError = std.testing.expectError;
 fn isFieldOptional(comptime T: type, field_index: usize) !bool {
     const fields = @typeInfo(T).Struct.fields;
     return switch (field_index) {
-        // This prong is analyzed `fields.len - 1` times with `idx` being an
+        // This prong is analyzed `fields.len - 1` times with `idx` being a
         // unique comptime-known value each time.
         inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .Optional,
         else => return error.IndexOutOfBounds,
@@ -8040,7 +8041,7 @@ pub const CallModifier = enum {
       <p>{#syntax#}@TypeOf(operand){#endsyntax#} must be an integer type or an integer vector type.</p>
       <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
       <p>
-      This function counts the number of most-significant (leading in a big-Endian sense) zeroes in an integer.
+      Counts the number of most-significant (leading in a big-endian sense) zeroes in an integer - "count leading zeroes".
       </p>
       <p>
       If {#syntax#}operand{#endsyntax#} is a {#link|comptime#}-known integer,
@@ -8190,7 +8191,7 @@ test "main" {
       <p>{#syntax#}@TypeOf(operand){#endsyntax#} must be an integer type or an integer vector type.</p>
       <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
       <p>
-      This function counts the number of least-significant (trailing in a big-Endian sense) zeroes in an integer.
+      Counts the number of least-significant (trailing in a big-endian sense) zeroes in an integer - "count trailing zeroes".
       </p>
       <p>
       If {#syntax#}operand{#endsyntax#} is a {#link|comptime#}-known integer,
@@ -8576,11 +8577,11 @@ test "@hasDecl" {
       </p>
       <ul>
           <li>{#syntax#}@import("std"){#endsyntax#} - Zig Standard Library</li>
-          <li>{#syntax#}@import("builtin"){#endsyntax#} - Target-specific information.
+          <li>{#syntax#}@import("builtin"){#endsyntax#} - Target-specific information
               The command <code>zig build-exe --show-builtin</code> outputs the source to stdout for reference.
           </li>
-          <li>{#syntax#}@import("root"){#endsyntax#} - Points to the root source file.
-              This is usually <code>src/main.zig</code> but it depends on what file is chosen to be built.
+          <li>{#syntax#}@import("root"){#endsyntax#} - Root source file
+              This is usually <code>src/main.zig</code> but depends on what file is built.
           </li>
       </ul>
       {#see_also|Compile Variables|@embedFile#}
@@ -8803,7 +8804,9 @@ test "@wasmMemoryGrow" {
       <pre>{#syntax#}@popCount(operand: anytype) anytype{#endsyntax#}</pre>
       <p>{#syntax#}@TypeOf(operand){#endsyntax#} must be an integer type.</p>
       <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
-      <p>Counts the number of bits set in an integer.</p>
+      <p>
+      Counts the number of bits set in an integer - "population count".
+      </p>
       <p>
       If {#syntax#}operand{#endsyntax#} is a {#link|comptime#}-known integer,
       the return type is {#syntax#}comptime_int{#endsyntax#}.
@@ -8835,6 +8838,8 @@ test "@wasmMemoryGrow" {
 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.
     ///
@@ -8844,12 +8849,12 @@ pub const PrefetchOptions = struct {
     /// The cache that the prefetch should be preformed on.
     cache: Cache = .data,
 
-    pub const Rw = enum {
+    pub const Rw = enum(u1) {
         read,
         write,
     };
 
-    pub const Cache = enum {
+    pub const Cache = enum(u1) {
         instruction,
         data,
     };
@@ -10971,7 +10976,7 @@ pub const MAKELOCAL = @compileError("unable to translate C expr: unexpected toke
       </p>
       <p>{#syntax#}[*c]T{#endsyntax#} - C pointer.</p>
       <ul>
-        <li>Supports all the syntax of the other two pointer types.</li>
+        <li>Supports all the syntax of the other two pointer types ({#syntax#}*T{#endsyntax#}) and ({#syntax#}[*]T{#endsyntax#}).</li>
         <li>Coerces to other pointer types, as well as {#link|Optional Pointers#}.
             When a C pointer is coerced to a non-optional pointer, safety-checked
             {#link|Undefined Behavior#} occurs if the address is 0.
diff --git a/lib/std/Build/Cache.zig b/lib/std/Build/Cache.zig
index 3b67f4b24cb725be9744f82b6330c3c441976d7f..cae779a3061ed879a6dce9a196dce52fa1d03deb 100644
--- a/lib/std/Build/Cache.zig
+++ b/lib/std/Build/Cache.zig
@@ -184,7 +184,7 @@ pub const File = struct {
 pub const HashHelper = struct {
     hasher: Hasher = hasher_init,
 
-    /// Record a slice of bytes as an dependency of the process being cached
+    /// Record a slice of bytes as a dependency of the process being cached.
     pub fn addBytes(hh: *HashHelper, bytes: []const u8) void {
         hh.hasher.update(mem.asBytes(&bytes.len));
         hh.hasher.update(bytes);
diff --git a/lib/std/RingBuffer.zig b/lib/std/RingBuffer.zig
index 857775b5a0a6673ab5abc198c00a6cf63dab4af1..080e6f54d32f49a4e3cc25ccb2988e68ca7f2a69 100644
--- a/lib/std/RingBuffer.zig
+++ b/lib/std/RingBuffer.zig
@@ -1,7 +1,7 @@
 //! This ring buffer stores read and write indices while being able to utilise
 //! the full backing slice by incrementing the indices modulo twice the slice's
 //! length and reducing indices modulo the slice's length on slice access. This
-//! means that whether the ring buffer if full or empty can be distinguished by
+//! means that whether the ring buffer is full or empty can be distinguished by
 //! looking at the difference between the read and write indices without adding
 //! an extra boolean flag or having to reserve a slot in the buffer.
 //!
diff --git a/lib/std/Uri.zig b/lib/std/Uri.zig
index b010ce86620e33abd2067b6b47aad6d1a347ef5f..b0bb3047cb318847dba164f35298ebf7aab1ec97 100644
--- a/lib/std/Uri.zig
+++ b/lib/std/Uri.zig
@@ -1,4 +1,4 @@
-//! Implements URI parsing roughly adhering to <https://tools.ietf.org/html/rfc3986>.
+//! Uniform Resource Identifier (URI) parsing roughly adhering to <https://tools.ietf.org/html/rfc3986>.
 //! Does not do perfect grammar and character class checking, but should be robust against URIs in the wild.
 
 const Uri = @This();
diff --git a/lib/std/array_list.zig b/lib/std/array_list.zig
index 205649ae4d3076b656a02c594071d0e75150ba5a..1695e2bd875febee8e4b70a2ea7d106d2edf4e93 100644
--- a/lib/std/array_list.zig
+++ b/lib/std/array_list.zig
@@ -221,6 +221,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
         /// Asserts the array has at least one item.
         /// Invalidates pointers to end of list.
         /// This operation is O(N).
+        /// This preserves item order. Use `swapRemove` if order preservation is not important.
         pub fn orderedRemove(self: *Self, i: usize) T {
             const newlen = self.items.len - 1;
             if (newlen == i) return self.pop();
@@ -235,6 +236,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
         /// Removes the element at the specified index and returns it.
         /// The empty slot is filled from the end of the list.
         /// This operation is O(1).
+        /// This may not preserve item order. Use `orderedRemove` if you need to preserve order.
         pub fn swapRemove(self: *Self, i: usize) T {
             if (self.items.len - 1 == i) return self.pop();
 
diff --git a/lib/std/bit_set.zig b/lib/std/bit_set.zig
index d8f9b7f90ef2f0951a8ddf7761b8fa22d23dd885..292d09930348e35a44461f587791b8bbeb845612 100644
--- a/lib/std/bit_set.zig
+++ b/lib/std/bit_set.zig
@@ -35,9 +35,10 @@ const assert = std.debug.assert;
 const Allocator = std.mem.Allocator;
 
 /// Returns the optimal static bit set type for the specified number
-/// of elements.  The returned type will perform no allocations,
+/// of elements: either `IntegerBitSet` or `ArrayBitSet`,
+/// both of which fulfill the same interface.
+/// The returned type will perform no allocations,
 /// can be copied by value, and does not require deinitialization.
-/// Both possible implementations fulfill the same interface.
 pub fn StaticBitSet(comptime size: usize) type {
     if (size <= @bitSizeOf(usize)) {
         return IntegerBitSet(size);
diff --git a/lib/std/builtin.zig b/lib/std/builtin.zig
index 1d28e69d61729715dd08ab861182085868fa7531..cfe22099cb4d8b9b1e1701ec01fb9d6e1eda6c16 100644
--- a/lib/std/builtin.zig
+++ b/lib/std/builtin.zig
@@ -144,22 +144,47 @@ pub const Mode = OptimizeMode;
 /// This data structure is used by the Zig language code generation and
 /// therefore must be kept in sync with the compiler implementation.
 pub const CallingConvention = enum {
+    /// This is the default Zig calling convention used when not using `export` on `fn`
+    /// and no other calling convention is specified.
     Unspecified,
+    /// Matches the C ABI for the target.
+    /// This is the default calling convention when using `export` on `fn`
+    /// and no other calling convention is specified.
     C,
+    /// This makes a function not have any function prologue or epilogue,
+    /// making the function itself uncallable in regular Zig code.
+    /// This can be useful when integrating with assembly.
     Naked,
+    /// Functions with this calling convention are called asynchronously,
+    /// as if called as `async function()`.
     Async,
+    /// Functions with this calling convention are inlined at all call sites.
     Inline,
+    /// x86-only.
     Interrupt,
     Signal,
+    /// x86-only.
     Stdcall,
+    /// x86-only.
     Fastcall,
+    /// x86-only.
     Vectorcall,
+    /// x86-only.
     Thiscall,
+    /// ARM Procedure Call Standard (obsolete)
+    /// ARM-only.
     APCS,
+    /// ARM Architecture Procedure Call Standard (current standard)
+    /// ARM-only.
     AAPCS,
+    /// ARM Architecture Procedure Call Standard Vector Floating-Point
+    /// ARM-only.
     AAPCSVFP,
+    /// x86-64-only.
     SysV,
+    /// x86-64-only.
     Win64,
+    /// AMD GPU, NVPTX, or SPIR-V kernel
     Kernel,
 };
 
@@ -716,6 +741,8 @@ pub const VaList = switch (builtin.cpu.arch) {
 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.
     ///
diff --git a/lib/std/compress/zstandard.zig b/lib/std/compress/zstandard.zig
index f59de87e6ba4d75c3e1bddfd90be0bd9dc895443..1e8a0fc86fb892d9c47b8855d246f2d38b2707ae 100644
--- a/lib/std/compress/zstandard.zig
+++ b/lib/std/compress/zstandard.zig
@@ -10,7 +10,7 @@ pub const decompress = @import("zstandard/decompress.zig");
 
 pub const DecompressStreamOptions = struct {
     verify_checksum: bool = true,
-    window_size_max: usize = 1 << 23, // 8MiB default maximum window size,
+    window_size_max: usize = 1 << 23, // 8MiB default maximum window size
 };
 
 pub fn DecompressStream(
diff --git a/lib/std/compress/zstandard/decode/fse.zig b/lib/std/compress/zstandard/decode/fse.zig
index 41a34d0fc15b0324ccfe2aea049f819bd1d31684..741fd81cccd8ad3f1990990ad06955299cf3c6a6 100644
--- a/lib/std/compress/zstandard/decode/fse.zig
+++ b/lib/std/compress/zstandard/decode/fse.zig
@@ -21,7 +21,7 @@ pub fn decodeFseTable(
     var accumulated_probability: u16 = 0;
 
     while (accumulated_probability < total_probability) {
-        // WARNING: The RFC in poorly worded, and would suggest std.math.log2_int_ceil is correct here,
+        // WARNING: The RFC is poorly worded, and would suggest std.math.log2_int_ceil is correct here,
         //          but power of two (remaining probabilities + 1) need max bits set to 1 more.
         const max_bits = std.math.log2_int(u16, total_probability - accumulated_probability + 1) + 1;
         const small = try bit_reader.readBitsNoEof(u16, max_bits - 1);
diff --git a/lib/std/debug.zig b/lib/std/debug.zig
index e093fa5dc8d11c1ab0a22684dbdcccf31a5fbd29..c965dd64367b688f671141f57bb3d0850947dfe9 100644
--- a/lib/std/debug.zig
+++ b/lib/std/debug.zig
@@ -651,6 +651,8 @@ pub fn writeCurrentStackTraceWindows(
     }
 }
 
+/// Provides simple functionality for manipulating the terminal in some way,
+/// for debugging purposes, such as coloring text, etc.
 pub const TTY = struct {
     pub const Color = enum {
         Red,
diff --git a/lib/std/fmt.zig b/lib/std/fmt.zig
index 3f697f811759ebc58dce4ae3c08eafbe2cfde728..e87c84eaa2877cda1d6653c6c3f66c731431dfa9 100644
--- a/lib/std/fmt.zig
+++ b/lib/std/fmt.zig
@@ -41,7 +41,7 @@ pub const FormatOptions = struct {
 ///     brackets, e.g. {[score]...} as opposed to the numeric index form which can be written e.g. {2...}
 /// - *specifier* is a type-dependent formatting option that determines how a type should formatted (see below)
 /// - *fill* is a single character which is used to pad the formatted text
-/// - *alignment* is one of the three characters `<`, `^` or `>`. they define if the text is *left*, *center*, or *right* aligned
+/// - *alignment* is one of the three characters `<`, `^`, or `>` to make the text left-, center-, or right-aligned, respectively
 /// - *width* is the total width of the field in characters
 /// - *precision* specifies how many decimals a formatted number should have
 ///
diff --git a/lib/std/fs/path.zig b/lib/std/fs/path.zig
index 4d780b2ead663f56ef256c08b8466521f18ff10c..beb386f92c1e321cb764717380584d8e7b6b8966 100644
--- a/lib/std/fs/path.zig
+++ b/lib/std/fs/path.zig
@@ -1214,10 +1214,9 @@ fn testRelativeWindows(from: []const u8, to: []const u8, expected_output: []cons
     try testing.expectEqualStrings(expected_output, result);
 }
 
-/// Returns the extension of the file name (if any).
-/// This function will search for the file extension (separated by a `.`) and will return the text after the `.`.
-/// Files that end with `.`, or that start with `.` and have no other `.` in their name,
-/// are considered to have no extension.
+/// Searches for a file extension separated by a `.` and returns the string after that `.`.
+/// Files that end or start with `.` and have no other `.` in their name
+/// are considered to have no extension, in which case this returns "".
 /// Examples:
 /// - `"main.zig"`      ⇒ `".zig"`
 /// - `"src/main.zig"`  ⇒ `".zig"`
diff --git a/lib/std/macho.zig b/lib/std/macho.zig
index ff12e718f6e47f414e8a80d6761f156f1a905705..a25ffca4fa33b6674a9cf35a8d8b4dec754cbde0 100644
--- a/lib/std/macho.zig
+++ b/lib/std/macho.zig
@@ -540,13 +540,13 @@ pub const dylib_command = extern struct {
     dylib: dylib,
 };
 
-/// Dynamicaly linked shared libraries are identified by two things.  The
+/// Dynamically linked shared libraries are identified by two things.  The
 /// pathname (the name of the library as found for execution), and the
 /// compatibility version number.  The pathname must match and the compatibility
 /// number in the user of the library must be greater than or equal to the
 /// library being used.  The time stamp is used to record the time a library was
 /// built and copied into user so it can be use to determined if the library used
-/// at runtime is exactly the same as used to built the program.
+/// at runtime is exactly the same as used to build the program.
 pub const dylib = extern struct {
     /// library's pathname (offset pointing at the end of dylib_command)
     name: u32,
diff --git a/lib/std/math.zig b/lib/std/math.zig
index 14c71a796ff325a1dd707f863c4dfaf32596c5a9..02b737610c52f784e5c0a342f9a37520b5cd429c 100644
--- a/lib/std/math.zig
+++ b/lib/std/math.zig
@@ -782,7 +782,8 @@ fn testOverflow() !void {
 }
 
 /// Returns the absolute value of x, where x is a value of a signed integer type.
-/// See also: `absCast`
+/// Does not convert and returns a value of a signed integer type.
+/// Use `absCast` if you want to convert the result and get an unsigned type.
 pub fn absInt(x: anytype) !@TypeOf(x) {
     const T = @TypeOf(x);
     return switch (@typeInfo(T)) {
@@ -1015,8 +1016,8 @@ pub inline fn fabs(value: anytype) @TypeOf(value) {
 }
 
 /// Returns the absolute value of the integer parameter.
-/// Result is an unsigned integer.
-/// See also: `absInt`
+/// Converts result type to unsigned if needed and returns a value of an unsigned integer type.
+/// Use `absInt` if you want to keep your integer type signed.
 pub fn absCast(x: anytype) switch (@typeInfo(@TypeOf(x))) {
     .ComptimeInt => comptime_int,
     .Int => |int_info| std.meta.Int(.unsigned, int_info.bits),
diff --git a/lib/std/mem.zig b/lib/std/mem.zig
index 940882e9303e37561cab36b322b3db27b981f322..4b796c851a46f534025edb02cb0ac2d23e077216 100644
--- a/lib/std/mem.zig
+++ b/lib/std/mem.zig
@@ -227,7 +227,7 @@ pub fn set(comptime T: type, dest: []T, value: T) void {
 /// interfacing with a C API where this practice is more common and relied upon. If you are performing code review and see this
 /// function used, examine closely - it may be a code smell.
 /// Zero initializes the type.
-/// This can be used to zero initialize a any type for which it makes sense. Structs will be initialized recursively.
+/// This can be used to zero-initialize any type for which it makes sense. Structs will be initialized recursively.
 pub fn zeroes(comptime T: type) T {
     switch (@typeInfo(T)) {
         .ComptimeInt, .Int, .ComptimeFloat, .Float => {
diff --git a/lib/std/os/linux/seccomp.zig b/lib/std/os/linux/seccomp.zig
index b659c3d0e8f368f84eb3c5ec2df5768c64a45cce..23dbb6ee3872be66b21ff7f61eb24625b9c6872e 100644
--- a/lib/std/os/linux/seccomp.zig
+++ b/lib/std/os/linux/seccomp.zig
@@ -20,7 +20,7 @@
 //!
 //! 1. Each CPU architecture supported by Linux has its own unique ABI and
 //!    syscall API. It is not guaranteed that the syscall numbers and arguments
-//!    are the same across architectures, or that they're even implemted. Thus,
+//!    are the same across architectures, or that they're even implemented. Thus,
 //!    filters cannot be assumed to be portable without consulting documentation
 //!    like syscalls(2) and testing on target hardware. This also requires
 //!    checking the value of `data.arch` to make sure that a filter was compiled
diff --git a/lib/std/rand.zig b/lib/std/rand.zig
index 4f9cb0db56a67dda4464f8a19fbf18889c7ea90b..204409c10edb0f49ed42054776b1c4ab8126344e 100644
--- a/lib/std/rand.zig
+++ b/lib/std/rand.zig
@@ -389,6 +389,8 @@ pub const Random = struct {
 
     /// Randomly selects an index into `proportions`, where the likelihood of each
     /// index is weighted by that proportion.
+    /// It is more likely for the index of the last proportion to be returned
+    /// than the index of the first proportion in the slice, and vice versa.
     ///
     /// This is useful for selecting an item from a slice where weights are not equal.
     /// `T` must be a numeric type capable of holding the sum of `proportions`.
diff --git a/src/Air.zig b/src/Air.zig
index 19ba576a5f98e7f7288442cb98459ec9b28d4dd3..33a8d0515bde6b1d1fdd2cc3467e8f357f75b30a 100644
--- a/src/Air.zig
+++ b/src/Air.zig
@@ -681,7 +681,7 @@ pub const Inst = struct {
         /// Uses the `un_op` field.
         tag_name,
 
-        /// Given an error value, return the error name. Result type is always `[:0] const u8`.
+        /// Given an error value, return the error name. Result type is always `[:0]const u8`.
         /// Uses the `un_op` field.
         error_name,
 
diff --git a/src/Autodoc.zig b/src/Autodoc.zig
index d24463f4c07d62baf24a1a4d688b8015a0188b32..9e8ebbf5a473da3d109c8894bea0b698eb866393 100644
--- a/src/Autodoc.zig
+++ b/src/Autodoc.zig
@@ -4076,7 +4076,7 @@ fn analyzeFancyFunction(
         else => null,
     };
 
-    // if we're analyzing a funcion signature (ie without body), we
+    // if we're analyzing a function signature (ie without body), we
     // actually don't have an ast_node reserved for us, but since
     // we don't have a name, we don't need it.
     const src = if (fn_info.body.len == 0) 0 else self_ast_node_index;
@@ -4229,7 +4229,7 @@ fn analyzeFunction(
         } else break :blk ret_type_ref;
     };
 
-    // if we're analyzing a funcion signature (ie without body), we
+    // if we're analyzing a function signature (ie without body), we
     // actually don't have an ast_node reserved for us, but since
     // we don't have a name, we don't need it.
     const src = if (fn_info.body.len == 0) 0 else self_ast_node_index;
diff --git a/src/Sema.zig b/src/Sema.zig
index 5c19d374316c1393bec09a7a5107a10a87b73909..4deb2b0f29e08c067bc3833fea7dba8703699f60 100644
--- a/src/Sema.zig
+++ b/src/Sema.zig
@@ -4155,7 +4155,7 @@ fn validateUnionInit(
             const msg = try sema.errMsg(
                 block,
                 init_src,
-                "cannot initialize multiple union fields at once, unions can only have one active field",
+                "cannot initialize multiple union fields at once; unions can only have one active field",
                 .{},
             );
             errdefer msg.destroy(sema.gpa);
@@ -9646,7 +9646,7 @@ fn zirBitcast(sema: *Sema, block: *Block, inst: Zir.Inst.Index) CompileError!Air
                 .Union => "union",
                 else => unreachable,
             };
-            return sema.fail(block, dest_ty_src, "cannot @bitCast to '{}', {s} does not have a guaranteed in-memory layout", .{
+            return sema.fail(block, dest_ty_src, "cannot @bitCast to '{}'; {s} does not have a guaranteed in-memory layout", .{
                 dest_ty.fmt(sema.mod), container,
             });
         },
@@ -9709,7 +9709,7 @@ fn zirBitcast(sema: *Sema, block: *Block, inst: Zir.Inst.Index) CompileError!Air
                 .Union => "union",
                 else => unreachable,
             };
-            return sema.fail(block, operand_src, "cannot @bitCast from '{}', {s} does not have a guaranteed in-memory layout", .{
+            return sema.fail(block, operand_src, "cannot @bitCast from '{}'; {s} does not have a guaranteed in-memory layout", .{
                 operand_ty.fmt(sema.mod), container,
             });
         },
@@ -26434,7 +26434,7 @@ fn coerceVarArgParam(
         .ComptimeInt, .ComptimeFloat => return sema.fail(
             block,
             inst_src,
-            "integer and float literals passed variadic function must be casted to a fixed-size number type",
+            "integer and float literals passed to variadic function must be casted to a fixed-size number type",
             .{},
         ),
         .Fn => blk: {
@@ -27891,7 +27891,7 @@ fn coerceAnonStructToUnion(
             const msg = if (field_count > 1) try sema.errMsg(
                 block,
                 inst_src,
-                "cannot initialize multiple union fields at once, unions can only have one active field",
+                "cannot initialize multiple union fields at once; unions can only have one active field",
                 .{},
             ) else try sema.errMsg(
                 block,
diff --git a/src/link/NvPtx.zig b/src/link/NvPtx.zig
index c542241cd91597a15bf4fd8d52487acc9a500857..69cd73a6025fcb6c8a7419cebdbb4c9398dee91a 100644
--- a/src/link/NvPtx.zig
+++ b/src/link/NvPtx.zig
@@ -1,4 +1,4 @@
-//! NVidia PTX (Paralle Thread Execution)
+//! NVidia PTX (Parallel Thread Execution)
 //! https://docs.nvidia.com/cuda/parallel-thread-execution/index.html
 //! For this we rely on the nvptx backend of LLVM
 //! Kernel functions need to be marked both as "export" and "callconv(.Kernel)"
diff --git a/src/main.zig b/src/main.zig
index 6a83791ca38fe4f8d2ef40abcb173f38529ffb52..66b207aa43520a732d22c20c53a505251efe65bf 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -402,8 +402,8 @@ const usage_build_generic =
     \\  --name [name]             Override root name (not a file path)
     \\  -O [mode]                 Choose what to optimize for
     \\    Debug                   (default) Optimizations off, safety on
-    \\    ReleaseFast             Optimizations on, safety off
-    \\    ReleaseSafe             Optimizations on, safety on
+    \\    ReleaseFast             Optimize for performance, safety off
+    \\    ReleaseSafe             Optimize for performance, safety on
     \\    ReleaseSmall            Optimize for small binary, safety off
     \\  --mod [name]:[deps]:[src] Make a module available for dependency under the given name
     \\      deps: [dep],[dep],...
diff --git a/test/cases/compile_errors/union_init_with_none_or_multiple_fields.zig b/test/cases/compile_errors/union_init_with_none_or_multiple_fields.zig
index a700f0d0f29aab5e275782a4952e14217fdf08c0..f808ec8227546d0cfaf5356159678f36caad75ef 100644
--- a/test/cases/compile_errors/union_init_with_none_or_multiple_fields.zig
+++ b/test/cases/compile_errors/union_init_with_none_or_multiple_fields.zig
@@ -29,10 +29,10 @@ export fn u2m() void {
 //
 // :9:1: error: union initializer must initialize one field
 // :1:12: note: union declared here
-// :14:20: error: cannot initialize multiple union fields at once, unions can only have one active field
+// :14:20: error: cannot initialize multiple union fields at once; unions can only have one active field
 // :14:31: note: additional initializer here
 // :1:12: note: union declared here
 // :18:21: error: union initializer must initialize one field
-// :22:20: error: cannot initialize multiple union fields at once, unions can only have one active field
+// :22:20: error: cannot initialize multiple union fields at once; unions can only have one active field
 // :22:31: note: additional initializer here
 // :5:12: note: union declared here
diff --git a/test/cases/compile_errors/variadic_arg_validation.zig b/test/cases/compile_errors/variadic_arg_validation.zig
index 830d3a087797a64aad7e7f28b51d54a331915c88..bddcef92f693b0f2cd67d044b9a47e7f57c95133 100644
--- a/test/cases/compile_errors/variadic_arg_validation.zig
+++ b/test/cases/compile_errors/variadic_arg_validation.zig
@@ -21,7 +21,7 @@ pub export fn entry3() void {
 // backend=stage2
 // target=native
 //
-// :4:33: error: integer and float literals passed variadic function must be casted to a fixed-size number type
+// :4:33: error: integer and float literals passed to variadic function must be casted to a fixed-size number type
 // :9:24: error: arrays must be passed by reference to variadic function
 // :13:24: error: cannot pass 'u48' to variadic function
 // :13:24: note: only integers with power of two bits are extern compatible
-- 
2.54.0