From 58f8dcd15e04a02185f4e18dbf76c54942e05350 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Tue, 19 May 2026 15:41:58 -0700
Subject: [PATCH] std.Build: improve documentation for UpdateSourceFiles step

---
 lib/std/Build.zig                        | 10 ++++++++++
 lib/std/Build/Step/UpdateSourceFiles.zig |  5 -----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/lib/std/Build.zig b/lib/std/Build.zig
index f2b0ed84d9..39b4b8993f 100644
--- a/lib/std/Build.zig
+++ b/lib/std/Build.zig
@@ -966,6 +966,16 @@ pub fn addWriteFiles(b: *Build) *Step.WriteFile {
     return Step.WriteFile.create(b);
 }
 
+/// Creates a step for writing data to paths relative to the build root,
+/// mutating the project's source files.
+///
+/// This build step was designed not to be used during the normal build
+/// process, but rather as a utility run by a developer with intention to
+/// update source files, which will then be committed to version control.
+///
+/// Example use cases:
+/// * precompiling assets which are tracked by version control
+/// * snapshot testing
 pub fn addUpdateSourceFiles(b: *Build) *Step.UpdateSourceFiles {
     return Step.UpdateSourceFiles.create(b);
 }
diff --git a/lib/std/Build/Step/UpdateSourceFiles.zig b/lib/std/Build/Step/UpdateSourceFiles.zig
index cc5b114b8c..11391ea7d2 100644
--- a/lib/std/Build/Step/UpdateSourceFiles.zig
+++ b/lib/std/Build/Step/UpdateSourceFiles.zig
@@ -1,8 +1,3 @@
-//! Writes data to paths relative to the package root, effectively mutating the
-//! package's source files. Be careful with the latter functionality; it should
-//! not be used during the normal build process, but as a utility run by a
-//! developer with intention to update source files, which will then be
-//! committed to version control.
 const UpdateSourceFiles = @This();
 
 const std = @import("std");