From c52a2c338d706862c2cc73f7321172eb24ab4430 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Mon, 18 Mar 2024 23:51:43 -0700
Subject: [PATCH] std.Build.Step.Run: documentation for addFileArg and friends

Someone on IRC got these functions mixed up, and it sure would have been
helpful to have these docs in the first place, eh?
---
 lib/std/Build/Step/Run.zig | 44 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/lib/std/Build/Step/Run.zig b/lib/std/Build/Step/Run.zig
index b0b5602a12..cb1ed7e7dc 100644
--- a/lib/std/Build/Step/Run.zig
+++ b/lib/std/Build/Step/Run.zig
@@ -168,13 +168,32 @@ pub fn addArtifactArg(self: *Run, artifact: *Step.Compile) void {
     self.argv.append(Arg{ .artifact = artifact }) catch @panic("OOM");
 }
 
-/// This provides file path as a command line argument to the command being
-/// run, and returns a LazyPath which can be used as inputs to other APIs
+/// Provides a file path as a command line argument to the command being run.
+///
+/// Returns a `std.Build.LazyPath` which can be used as inputs to other APIs
 /// throughout the build system.
+///
+/// Related:
+/// * `addPrefixedOutputFileArg` - same thing but prepends a string to the argument
+/// * `addFileArg` - for input files given to the child process
 pub fn addOutputFileArg(self: *Run, basename: []const u8) std.Build.LazyPath {
     return self.addPrefixedOutputFileArg("", basename);
 }
 
+/// Provides a file path as a command line argument to the command being run.
+///
+/// For example, a prefix of "-o" and basename of "output.txt" will result in
+/// the child process seeing something like this: "-ozig-cache/.../output.txt"
+///
+/// The child process will see a single argument, regardless of whether the
+/// prefix or basename have spaces.
+///
+/// The returned `std.Build.LazyPath` can be used as inputs to other APIs
+/// throughout the build system.
+///
+/// Related:
+/// * `addOutputFileArg` - same thing but without the prefix
+/// * `addFileArg` - for input files given to the child process
 pub fn addPrefixedOutputFileArg(
     self: *Run,
     prefix: []const u8,
@@ -197,10 +216,31 @@ pub fn addPrefixedOutputFileArg(
     return .{ .generated = &output.generated_file };
 }
 
+/// Appends an input file to the command line arguments.
+///
+/// The child process will see a file path. Modifications to this file will be
+/// detected as a cache miss in subsequent builds, causing the child process to
+/// be re-executed.
+///
+/// Related:
+/// * `addPrefixedFileArg` - same thing but prepends a string to the argument
+/// * `addOutputFileArg` - for files generated by the child process
 pub fn addFileArg(self: *Run, lp: std.Build.LazyPath) void {
     self.addPrefixedFileArg("", lp);
 }
 
+/// Appends an input file to the command line arguments prepended with a string.
+///
+/// For example, a prefix of "-F" will result in the child process seeing something
+/// like this: "-Fexample.txt"
+///
+/// The child process will see a single argument, even if the prefix has
+/// spaces. Modifications to this file will be detected as a cache miss in
+/// subsequent builds, causing the child process to be re-executed.
+///
+/// Related:
+/// * `addFileArg` - same thing but without the prefix
+/// * `addOutputFileArg` - for files generated by the child process
 pub fn addPrefixedFileArg(self: *Run, prefix: []const u8, lp: std.Build.LazyPath) void {
     const b = self.step.owner;