Add more documentation for rule.outputs

We want to simplify/remove this API, but let's document it in the meantime.

Also fix harmless bug that annoyed me. It used rawTemplate instead of formatStr when there are no placeholders. This would theoretically fail to properly escape % symbols, except that the code path luckily short-circuits later on if there are no placeholders.

RELNOTES:
PiperOrigin-RevId: 189760809

1 files changed, 29 insertions, 11 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java
index fd60a1835b..fb01a4a9c7 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java
@@ -414,11 +414,12 @@ public class SkylarkRuleClassFunctions {
         noneable = true,
         defaultValue = "None",
         doc =
-            "A schema for defining predeclared outputs. Unlike <a href='attr.html#output'><code>"
-                + "output</code></a> and <a href='attr.html#output_list'><code>output_list</code>"
-                + "</a> attributes, the user does not specify the labels for these files. See the "
-                + "<a href='../rules.$DOC_EXT#files'>Rules page</a> for more on predeclared "
-                + "outputs."
+            "<b>Experimental:</b> This API is in the process of being redesigned."
+                + "<p>A schema for defining predeclared outputs. Unlike <a href='attr.html#output'>"
+                + "<code>output</code></a> and <a href='attr.html#output_list'><code>output_list"
+                + "</code></a> attributes, the user does not specify the labels for these files. "
+                + "See the <a href='../rules.$DOC_EXT#files'>Rules page</a> for more on "
+                + "predeclared outputs."
                 + "<p>The value of this argument is either a dictionary or a callback function "
                 + "that produces a dictionary. The callback works similar to computed dependency "
                 + "attributes: The function's parameter names are matched against the rule's "
@@ -433,12 +434,29 @@ public class SkylarkRuleClassFunctions {
                 + "name used to access the output's <a href='File.html'><code>File</code></a> in "
                 + "<a href='ctx.html#outputs'><code>ctx.outputs</code></a>. The output's label has "
                 + "the same package as the rule, and the part after the package is produced by "
-                + "substituting each placeholder of the form <code>\"%{ATTR}\"</code> with the "
-                + "value of the attribute <code>ATTR</code>. In practice, the most common "
-                + "substitution placeholder is <code>\"%{name}\"</code>. For example, for a target "
-                + "named \"foo\", the outputs dict <code>{\"bin\": \"%{name}.exe\"}</code> "
-                + "predeclares an output named <code>foo.exe</code> that is accessable in the "
-                + "implementation function as <code>ctx.outputs.bin</code>."
+                + "substituting each placeholder of the form <code>\"%{ATTR}\"</code> with a "
+                + "string formed from the value of the attribute <code>ATTR</code>:"
+                + "<ul>"
+                + "<li>String-typed attributes are substituted verbatim."
+                + "<li>Label-typed attributes become the part of the label after the package, "
+                + "minus the file extension. For example, the label <code>\"//pkg:a/b.c\"</code> "
+                + "becomes <code>\"a/b\"</code>."
+                + "<li>Output-typed attributes become the part of the label after the package, "
+                + "including the file extension (for the above example, <code>\"a/b.c\"</code>)."
+                + "<li>All list-typed attributes (for example, <code>attr.label_list</code>) used "
+                + "in placeholders are required to have <i>exactly one element</i>. Their "
+                + "conversion is the same as their non-list version (<code>attr.label</code>)."
+                + "<li>Other attribute types may not appear in placeholders."
+                + "<li>The special non-attribute placeholders <code>%{dirname}</code> and <code>"
+                + "%{basename}</code> expand to those parts of the rule's label, excluding its "
+                + "package. For example, in <code>\"//pkg:a/b.c\"</code>, the dirname is <code>"
+                + "a</code> and the basename is <code>b.c</code>."
+                + "</ul>"
+                + "<p>In practice, the most common substitution placeholder is "
+                + "<code>\"%{name}\"</code>. For example, for a target named \"foo\", the outputs "
+                + "dict <code>{\"bin\": \"%{name}.exe\"}</code> predeclares an output named "
+                + "<code>foo.exe</code> that is accessible in the implementation function as "
+                + "<code>ctx.outputs.bin</code>."
       ),
       @Param(
         name = "executable",