Document the bazel contract for writing parameter files to disk.
RELNOTES: None
PiperOrigin-RevId: 210589287
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java
index 0a34af6..4164e21 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java
@@ -489,7 +489,11 @@
name = "use_param_file",
doc =
"Spills the args to a params file, replacing them with a pointer to the param file. "
- + "Use when your args may be too large for the system's command length limits ",
+ + "Use when your args may be too large for the system's command length limits."
+ + "<p>Bazel may choose to elide writing the params file to the output tree during "
+ + "execution for efficiency."
+ + "If you are debugging actions and want to inspect the param file, "
+ + "pass <code>--materialize_param_files</code> to your build.",
parameters = {
@Param(
name = "param_file_arg",
