From 61dcfc77ceced86883e156d45a4c675d6d11278c Mon Sep 17 00:00:00 2001
From: brandjon <brandjon@google.com>
Date: Mon, 26 Feb 2018 08:38:43 -0800
Subject: Revamp docs for default outputs / output groups

- collapsed these into one section
- removed the term "implicit outputs"
- add explanation for what these are first, then how to control them
- update docs for DefaultInfo
- also update docs for test/executable args of rule()

RELNOTES: None
PiperOrigin-RevId: 187026641
---
 .../skylark/SkylarkRuleClassFunctions.java         | 62 ++++++++++++++--------
 1 file changed, 39 insertions(+), 23 deletions(-)

(limited to 'src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java')

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 6f7a1bfd62..5e30bb4abe 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
@@ -232,23 +232,33 @@ public class SkylarkRuleClassFunctions {
     name = "DefaultInfo",
     returnType = Provider.class,
     doc =
-        "A provider that is provided by every rule, even if it is not returned explicitly. "
-            + "A <code>DefaultInfo</code> accepts the following parameters:"
+        "A provider that gives general information about a target's direct and transitive files. "
+            + "Every rule type has this provider, even if it is not returned explicitly by the "
+            + "rule's implementation function."
+            + "<p>The <code>DefaultInfo</code> constructor accepts the following parameters:"
             + "<ul>"
-            + "<li><code>executable</code></li>"
-            + "<li><code>files</code></li>"
-            + "<li><code>runfiles</code></li>"
-            + "<li><code>data_runfiles</code></li>"
-            + "<li><code>default_runfiles</code></li>"
+            + "<li><code>executable</code>: If this rule is marked "
+            + "<a href='globals.html#rule.executable'><code>executable</code></a> or "
+            + "<a href='globals.html#rule.test'><code>test</code></a>, this is a "
+            + "<a href='File.html'><code>File</code></a> object representing the file that should "
+            + "be executed to run the target. By default it is the predeclared output "
+            + "<code>ctx.outputs.executable</code>."
+            + "<li><code>files</code>: A <a href='depset.html'><code>depset<code></a> of "
+            + "<a href='File.html'><code>File</code></a> objects representing the default outputs "
+            + "to build when this target is specified on the blaze command line. By default it is "
+            + "all predeclared outputs."
+            + "<li><code>runfiles</code>"
+            + "<li><code>data_runfiles</code>"
+            + "<li><code>default_runfiles</code>"
             + "</ul>"
-            + "Each instance of the default provider contains the following standard "
-            + "fields: "
+            + "Each <code>DefaultInfo</code> instance has the following fields: "
             + "<ul>"
-            + "<li><code>files</code></li>"
-            + "<li><code>files_to_run</code></li>"
-            + "<li><code>data_runfiles</code></li>"
-            + "<li><code>default_runfiles</code></li>"
+            + "<li><code>files</code>"
+            + "<li><code>files_to_run</code>"
+            + "<li><code>data_runfiles</code>"
+            + "<li><code>default_runfiles</code>"
             + "</ul>"
+            + "See the <a href='../rules.$DOC_EXT'>rules</a> page for more information."
   )
   private static final Provider defaultInfo = DefaultInfo.PROVIDER;
 
@@ -256,12 +266,12 @@ public class SkylarkRuleClassFunctions {
     name = "OutputGroupInfo",
     returnType = Provider.class,
     doc =
-        "Provides information about output groups the rule provides.<br>"
+        "A provider that indicates what output groups a rule has.<br>"
             + "Instantiate this provider with <br>"
             + "<pre class=language-python>"
             + "OutputGroupInfo(group1 = &lt;files&gt;, group2 = &lt;files&gt;...)</pre>"
-            + "See <a href=\"../rules.$DOC_EXT#output-groups\">Output Groups</a> "
-            + "for more information."
+            + "See <a href=\"../rules.$DOC_EXT#requesting-output-files\">Requesting output files"
+            + "</a> for more information."
   )
   private static final Provider outputGroupInfo = OutputGroupInfo.SKYLARK_CONSTRUCTOR;
 
@@ -374,10 +384,14 @@ public class SkylarkRuleClassFunctions {
         type = Boolean.class,
         defaultValue = "False",
         doc =
-            "Whether this rule is a test rule. "
-                + "If True, the rule must end with <code>_test</code> (otherwise it must "
-                + "not), and there must be an action that generates "
-                + "<code>ctx.outputs.executable</code>."
+            "Whether this rule is a test rule, that is, whether it may be the subject of a "
+                + "<code>blaze test</code> or <code>blaze run</code> command. All test rules are "
+                + "automatically considered <a href='#rule.executable'>executable</a>; it is "
+                + "unnecessary (and discouraged) to explicitly set <code>executable = True</code> "
+                + "for a test rule."
+                + "<p>Test rules must have names ending in the suffix <code>\"_test\"</code>; "
+                + "non-test rules must not use this suffix. (Note that this applies only to the "
+                + "name of the rule, not its targets.)"
       ),
       @Param(
         name = "attrs",
@@ -418,9 +432,11 @@ public class SkylarkRuleClassFunctions {
         type = Boolean.class,
         defaultValue = "False",
         doc =
-            "whether this rule is marked as executable or not. If True, "
-                + "there must be an action that generates "
-                + "<code>ctx.outputs.executable</code>."
+            "Whether this rule is considered executable, that is, whether it may be the subject of "
+                + "a <code>blaze run</code> command. Executable rules automatically get a "
+                + "predeclared output that is addressable as <code>ctx.outputs.executable</code>. "
+                + "See the <a href='../rules.$DOC_EXT#output-files'>Rules page</a> for more "
+                + "information."
       ),
       @Param(
         name = "output_to_genfiles",
-- 
cgit v1.2.3