From d99e44a157dee9204c38e66bf7eba00c051690ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carl=20=C3=85stholm?= <carl@astholm.se>
Date: Sun, 10 Mar 2024 12:17:33 +0100
Subject: [PATCH] Document added/updated functions

Also renames `addHeaders` to `addHeadersDirectory` for clarity.
---
 lib/std/Build.zig                         |  7 ++++---
 lib/std/Build/Step/Compile.zig            | 14 +++++++++++++-
 lib/std/Build/Step/WriteFile.zig          |  3 +++
 test/standalone/install_headers/build.zig |  2 +-
 4 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/lib/std/Build.zig b/lib/std/Build.zig
index f0ef8b9a4a..50aa5c504c 100644
--- a/lib/std/Build.zig
+++ b/lib/std/Build.zig
@@ -1568,21 +1568,22 @@ pub fn addObjCopy(b: *Build, source: LazyPath, options: Step.ObjCopy.Options) *S
     return Step.ObjCopy.create(b, source, options);
 }
 
-///`dest_rel_path` is relative to install prefix path
+/// `dest_rel_path` is relative to install prefix path
 pub fn addInstallFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
     return b.addInstallFileWithDir(source, .prefix, dest_rel_path);
 }
 
-///`dest_rel_path` is relative to bin path
+/// `dest_rel_path` is relative to bin path
 pub fn addInstallBinFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
     return b.addInstallFileWithDir(source, .bin, dest_rel_path);
 }
 
-///`dest_rel_path` is relative to lib path
+/// `dest_rel_path` is relative to lib path
 pub fn addInstallLibFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
     return b.addInstallFileWithDir(source, .lib, dest_rel_path);
 }
 
+/// `dest_rel_path` is relative to header path
 pub fn addInstallHeaderFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
     return b.addInstallFileWithDir(source, .header, dest_rel_path);
 }
diff --git a/lib/std/Build/Step/Compile.zig b/lib/std/Build/Step/Compile.zig
index d7e8ec8ed3..2883992c73 100644
--- a/lib/std/Build/Step/Compile.zig
+++ b/lib/std/Build/Step/Compile.zig
@@ -446,6 +446,9 @@ pub fn create(owner: *std.Build, options: Options) *Compile {
     return self;
 }
 
+/// Marks the specified header for installation alongside this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
 pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8) void {
     const b = cs.step.owner;
     const installation: HeaderInstallation = .{ .file = .{
@@ -457,7 +460,10 @@ pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8)
     installation.getSource().addStepDependencies(&cs.step);
 }
 
-pub fn installHeaders(
+/// Marks headers from the specified directory for installation alongside this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
+pub fn installHeadersDirectory(
     cs: *Compile,
     source: LazyPath,
     dest_rel_path: []const u8,
@@ -474,10 +480,16 @@ pub fn installHeaders(
     installation.getSource().addStepDependencies(&cs.step);
 }
 
+/// Marks the specified config header for installation alongside this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
 pub fn installConfigHeader(cs: *Compile, config_header: *Step.ConfigHeader) void {
     cs.installHeader(config_header.getOutput(), config_header.include_path);
 }
 
+/// Forwards all headers marked for installation from `lib` to this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
 pub fn installLibraryHeaders(cs: *Compile, lib: *Compile) void {
     assert(lib.kind == .lib);
     const b = cs.step.owner;
diff --git a/lib/std/Build/Step/WriteFile.zig b/lib/std/Build/Step/WriteFile.zig
index f0ff6cfa70..310decdfe7 100644
--- a/lib/std/Build/Step/WriteFile.zig
+++ b/lib/std/Build/Step/WriteFile.zig
@@ -126,6 +126,9 @@ pub fn addCopyFile(wf: *WriteFile, source: std.Build.LazyPath, sub_path: []const
     return file.getPath();
 }
 
+/// Copy files matching the specified exclude/include patterns to the specified subdirectory
+/// relative to this step's generated directory.
+/// The returned value is a lazy path to the generated subdirectory.
 pub fn addCopyDirectory(
     wf: *WriteFile,
     source: std.Build.LazyPath,
diff --git a/test/standalone/install_headers/build.zig b/test/standalone/install_headers/build.zig
index 69206fb59d..965239aac5 100644
--- a/test/standalone/install_headers/build.zig
+++ b/test/standalone/install_headers/build.zig
@@ -32,7 +32,7 @@ pub fn build(b: *std.Build) void {
         \\}
     ) });
 
-    libfoo.installHeaders(.{ .path = "include" }, "foo", .{ .exclude_extensions = &.{".ignore_me.h"} });
+    libfoo.installHeadersDirectory(.{ .path = "include" }, "foo", .{ .exclude_extensions = &.{".ignore_me.h"} });
     libfoo.installHeader(b.addWriteFiles().add("d.h",
         \\#define FOO_D "D"
         \\