Inconsistencies in ways of reffering to commands, directories, files and code in comments #36064

K4 commented 2026年07月06日 11:46:21 +02:00

Here are some examples:

1. Comments referring to commands and flags:

• lib/std/Build.zig#L2456:

/// Path to the Zig executable being used to execute "zig build".

• lib/std/Build.zig#L2761:

/// of `zig build` into a cache miss.

• src/main.zig#L4938:

// Special case: if first arg starts with --zig-lib= then it is handled here.

• lib/std/Build/Step/Compile.zig#L699:

/// To run an executable built with zig build, use `run`, or create an install step and invoke it.

• lib/init/src/main.zig#L48:

// Try passing `--fuzz` to `zig build test` and see if it manages to fail this test case!

• lib/compiler/Maker/Fetch/git.zig#L297:

// Consistent with git archive behavior, create the directory but

---

2. Comments referring to directories:

• lib/std/Build.zig#L2458:

/// Path to the "lib/" directory from the Zig installation being used to

• lib/std/Build.zig#L2461:

/// Path to the project's local cache directory (usually called ".zig-cache").

• lib/std/Build.zig#L2682:

/// Creates a path leading to a directory inside "tmp" subdirectory of local

• lib/compiler/Maker/Step/ConfigHeader.zig#L127:

// We want to open directory zig-cache/o/HASH/libavutil/

• lib/std/zig/Server.zig#L132:

/// * the hex digest of the cache directory within the /o/ subdirectory.

• lib/std/zig/system.zig#L1067:

// Android does not have a /usr directory, so try again

---

3. Comments referring to files:

• lib/std/Build.zig#L2754:

/// Indicates that the build.zig logic depends on a particular file's contents.

• test/tests.zig#L2531:

"info: created build.zig.zon\n"

• test/tests.zig#L2573:

"info: successfully populated 'build.zig.zon' and 'build.zig'\n"

• lib/compiler/Maker.zig#L1868:

// their `build.zig.zon` *after* writing their `build.zig`. So this one isn't fatal.

---

4. Comments referring to code:

• lib/std/Build.zig#L2598:

/// The `graph` parameter is only used for the global arena allocator.

• lib/std/Build.zig#L2719:

/// If left as null, then the default will depend on system_package_mode.

• lib/std/Build.zig#L2763:

/// Only a subset of `LazyPath` are supported:

• lib/std/Build.zig#L2858-2859:

// build.zig script (or, frankly, this configure runner), therefore we call
// exit directly here rather than cleanExit.

• lib/std/Thread.zig#L313:

/// * the RLIMIT_NPROC soft resource limit (set via setrlimit(2)),

• lib/std/Thread.zig#L505:

// Faster than calling into GetSystemInfo(), even if amortized.

• lib/std/os/linux/IoUring.zig#L765:

/// Queues (but does not submit) an SQE to perform an `openat(2)`.

• lib/std/math/big/int.zig#L1912:

/// The upper bound is `calcTwosCompLimbCount(a.len)`.

---

For this issue to be closed, we need to have a list of rules to have a consistent way to refer to commands, flags, directories, files and code in comments that would be apllied across the entire codebase. Perhaps these rules should be included in zig's Style Guide.

**Here are some examples:** 1. Comments referring to commands and flags: - [lib/std/Build.zig#L2456](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2456): ``` /// Path to the Zig executable being used to execute "zig build". ``` - [lib/std/Build.zig#L2761](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2761): ``` /// of `zig build` into a cache miss. ``` - [src/main.zig#L4938](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/src/main.zig#L4938): ``` // Special case: if first arg starts with --zig-lib= then it is handled here. ``` - [lib/std/Build/Step/Compile.zig#L699](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build/Step/Compile.zig#L699): ``` /// To run an executable built with zig build, use `run`, or create an install step and invoke it. ``` - [lib/init/src/main.zig#L48](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/init/src/main.zig#L48): ``` // Try passing `--fuzz` to `zig build test` and see if it manages to fail this test case! ``` - [lib/compiler/Maker/Fetch/git.zig#L297](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/compiler/Maker/Fetch/git.zig#L297): ``` // Consistent with git archive behavior, create the directory but ``` ------------------------------------------------------------------------------------------------------------------------------------------------- 2. Comments referring to directories: - [lib/std/Build.zig#L2458](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2458): ``` /// Path to the "lib/" directory from the Zig installation being used to ``` - [lib/std/Build.zig#L2461](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2461): ``` /// Path to the project's local cache directory (usually called ".zig-cache"). ``` - [lib/std/Build.zig#L2682](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2682): ``` /// Creates a path leading to a directory inside "tmp" subdirectory of local ``` - [lib/compiler/Maker/Step/ConfigHeader.zig#L127](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/compiler/Maker/Step/ConfigHeader.zig#L127): ``` // We want to open directory zig-cache/o/HASH/libavutil/ ``` - [lib/std/zig/Server.zig#L132](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/zig/Server.zig#L132): ``` /// * the hex digest of the cache directory within the /o/ subdirectory. ``` - [lib/std/zig/system.zig#L1067](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/zig/system.zig#L1067): ``` // Android does not have a /usr directory, so try again ``` ------------------------------------------------------------------------------------------------------------------------------------------------- 3. Comments referring to files: - [lib/std/Build.zig#L2754](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2754): ``` /// Indicates that the build.zig logic depends on a particular file's contents. ``` - [test/tests.zig#L2531](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/test/tests.zig#L2531): ``` "info: created build.zig.zon\n" ``` - [test/tests.zig#L2573](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/test/tests.zig#L2573): ``` "info: successfully populated 'build.zig.zon' and 'build.zig'\n" ``` - [lib/compiler/Maker.zig#L1868](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/compiler/Maker.zig#L1868): ``` // their `build.zig.zon` *after* writing their `build.zig`. So this one isn't fatal. ``` ------------------------------------------------------------------------------------------------------------------------------------------------- 4. Comments referring to code: - [lib/std/Build.zig#L2598](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2598): ``` /// The `graph` parameter is only used for the global arena allocator. ``` - [lib/std/Build.zig#L2719](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2719): ``` /// If left as null, then the default will depend on system_package_mode. ``` - [lib/std/Build.zig#L2763](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2763): ``` /// Only a subset of `LazyPath` are supported: ``` - [lib/std/Build.zig#L2858-2859](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Build.zig#L2858-2859): ``` // build.zig script (or, frankly, this configure runner), therefore we call // exit directly here rather than cleanExit. ``` - [lib/std/Thread.zig#L313](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Thread.zig#L313): ``` /// * the RLIMIT_NPROC soft resource limit (set via setrlimit(2)), ``` - [lib/std/Thread.zig#L505](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/Thread.zig#L505): ``` // Faster than calling into GetSystemInfo(), even if amortized. ``` - [lib/std/os/linux/IoUring.zig#L765](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/os/linux/IoUring.zig#L765): ``` /// Queues (but does not submit) an SQE to perform an `openat(2)`. ``` - [lib/std/math/big/int.zig#L1912](https://codeberg.org/ziglang/zig/src/commit/c0f9b51d846e71f46f37ffa010152c7776d77991/lib/std/math/big/int.zig#L1912): ``` /// The upper bound is `calcTwosCompLimbCount(a.len)`. ``` ------------------------------------------------------------------------------------------------------------------------------------------------- For this issue to be closed, we need to have a list of rules to have a consistent way to refer to commands, flags, directories, files and code in comments that would be apllied across the entire codebase. Perhaps these rules should be included in zig's [Style Guide](https://ziglang.org/documentation/master/#Style-Guide).