Revamp docs for ctx.outputs

Explain the deprecation of ctx.outputs.executable.

RELNOTES: None
PiperOrigin-RevId: 187640408

2 files changed, 44 insertions, 20 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 "
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java
index fe468845c5..b1196fe1fe 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java
@@ -161,23 +161,32 @@ public final class SkylarkRuleContext implements SkylarkValue {
           + "attr struct, but their values will be single lists with all the branches of the split "
           + "merged together.";
   public static final String OUTPUTS_DOC =
-      "A pseudo-struct containing all the pre-declared output files."
-          + " It is generated the following way:<br>"
-          + "<ul>" + ""
-          + "<li>For every entry in the rule's <code>outputs</code> dict an attr is generated with "
-          + "the same name and the corresponding <code>file</code> value."
-          + "<li>For every output type attribute a struct attribute is generated with the "
-          + "same name and the corresponding <code>file</code> value or <code>None</code>, "
-          + "if no value is specified in the rule."
-          + "<li>For every output list type attribute a struct attribute is generated with the "
-          + "same name and corresponding <code>list</code> of <code>file</code>s value "
-          + "(an empty list if no value is specified in the rule).</li>"
-          + "<li>DEPRECATED: If the rule is marked as <code>executable=True</code>, a field "
-          + "\"executable\" can be accessed. That will declare the rule's default executable "
-          + "<code>File</code> value. The recommended alternative is to declare an executable with "
-          + "<a href=\"actions.html#declare_file\"><code>ctx.actions.declare_file</code></a> "
-          + "and return it as the <code>executable</code> field of the rule's "
-          + "<a href=\"globals.html#DefaultInfo\"><code>DefaultInfo</code></a> provider."
+      "A pseudo-struct containing all the predeclared output files, represented by "
+          + "<a href='File.html'><code>File</code></a> objects. See the "
+          + "<a href='../rules.$DOC_EXT#files'>Rules page</a> for more information and examples."
+          + "<p>This field does not exist on aspect contexts, since aspects do not have "
+          + "predeclared outputs."
+          + "<p>The fields of this object are defined as follows. It is an error if two outputs "
+          + "produce the same field name or have the same label."
+          + "<ul>"
+          + "<li>If the rule declares an <a href='globals.html#rule.outputs'><code>outputs</code>"
+          + "</a> dict, then for every entry in the dict, there is a field whose name is the key "
+          + "and whose value is the corresponding <code>File</code>."
+          + "<li>For every attribute of type <a href='attr.html#output'><code>attr.output</code>"
+          + "</a> that the rule declares, there is a field whose name is the attribute's name. "
+          + "If the target specified a label for that attribute, then the field value is the "
+          + "corresponding <code>File</code>; otherwise the field value is <code>None</code>."
+          + "<li>For every attribute of type <a href='attr.html#output_list'><code>attr.output_list"
+          + "</code></a> that the rule declares, there is a field whose name is the attribute's "
+          + "name. The field value is a list of <code>File</code> objects corresponding to the "
+          + "labels given for that attribute in the target, or an empty list if the attribute was "
+          + "not specified in the target."
+          + "<li><b>(Deprecated)</b> If the rule is marked <a href='globals.html#rule.executable'>"
+          + "<code>executable</code></a> or <a href='globals.html#rule.test'><code>test</code></a>,"
+          + "there is a field named <code>\"executable\"</code>, which is the default executable. "
+          + "It is recommended that instead of using this, you pass another file (either "
+          + "predeclared or not) to the <code>executable</code> arg of "
+          + "<a href='globals.html#DefaultInfo'><code>DefaultInfo</code></a>."
           + "</ul>";
   public static final Function<Attribute, Object> ATTRIBUTE_VALUE_EXTRACTOR_FOR_ASPECT =
       new Function<Attribute, Object>() {