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");