1 files changed, 26 insertions, 17 deletions
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>() {