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 a8af959615..254f119d3d 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 3b67f4b24c..cae779a306 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 857775b5a0..080e6f54d3 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 b010ce8662..b0bb3047cb 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 205649ae4d..1695e2bd87 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 d8f9b7f90e..292d099303 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 1d28e69d61..cfe22099cb 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 f59de87e6b..1e8a0fc86f 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 41a34d0fc1..741fd81ccc 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 e093fa5dc8..c965dd6436 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 3f697f8117..e87c84eaa2 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 4d780b2ead..beb386f92c 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 ff12e718f6..a25ffca4fa 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 14c71a796f..02b737610c 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 940882e930..4b796c851a 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 b659c3d0e8..23dbb6ee38 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 4f9cb0db56..204409c10e 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 19ba576a5f..33a8d0515b 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 d24463f4c0..9e8ebbf5a4 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 5c19d37431..4deb2b0f29 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 c542241cd9..69cd73a602 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 6a83791ca3..66b207aa43 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 a700f0d0f2..f808ec8227 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 830d3a0877..bddcef92f6 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