Revamp docs for ctx.outputs

Explain the deprecation of ctx.outputs.executable.

RELNOTES: None
PiperOrigin-RevId: 187640408

1 files changed, 18 insertions, 3 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 c5096c9c6b..f807715824 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
@@ -412,9 +412,24 @@ public class SkylarkRuleClassFunctions {
         noneable = true,
         defaultValue = "None",
         doc =
-            "outputs of this rule. "
-                + "It is a dictionary mapping from string to a template name. "
-                + "For example: <code>{\"ext\": \"%{name}.ext\"}</code>. <br>"
+            "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 a dictionary. Each entry creates a predeclared "
+                + "output where the key is an identifier and the value helps determine the "
+                + "output's label. In the rule's implementation function, the identifier becomes "
+                + "the field 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>."
+                + "<p>The output's label has the same package as the rule, and the part after the "
+                + "package is determined by the dict entry's value. If this value is a string, "
+                + "then it is interpreted as a template, where substitution placeholders of the "
+                + "form <code>\"%{ATTR}\"</code> are replaced by the value of the string attribute "
+                + "named <code>ATTR</code>. (For this purpose, the rule's <code>name</code> is "
+                + "also considered an attribute.) For example, the outputs dict "
+                + "<code>{\"bin\": \"%{name}.exe\"} predeclares an output with"
+                + "</code>. <br>"
                 + "The dictionary key becomes an attribute in <code>ctx.outputs</code>. "
                 + "Similar to computed dependency rule attributes, you can also specify the "
                 + "name of a function that returns the dictionary. This function can access "