Revamp discussion of executable/test rules

Rewrite that part of rules.md and update rule() docs. Also clarify the Action object's docs to put it in context.

RELNOTES: None
PiperOrigin-RevId: 187636896

1 files changed, 14 insertions, 13 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 b58432c1ef..c5096c9c6b 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
@@ -359,8 +359,12 @@ public class SkylarkRuleClassFunctions {
   @SkylarkSignature(
     name = "rule",
     doc =
-        "Creates a new rule. Store it in a global value, so that it can be loaded and called "
-            + "from BUILD files.",
+        "Creates a new rule, which can be called from a BUILD file or a macro to create targets."
+            + "<p>Rules must be assigned to global variables in a .bzl file; the name of the "
+            + "global variable is the rule's name."
+            + "<p>Test rules are required to have a name ending in <code>_test</code>, while all "
+            + "other rules must not have this suffix. (This restriction applies only to rules, not "
+            + "to their targets.)",
     returnType = BaseFunction.class,
     parameters = {
       @Param(
@@ -379,13 +383,11 @@ public class SkylarkRuleClassFunctions {
         defaultValue = "False",
         doc =
             "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.)"
+                + "<code>blaze test</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. See the "
+                + "<a href='../rules.$DOC_EXT#executable-rules-and-test-rules'>Rules page</a> for "
+                + "more information."
       ),
       @Param(
         name = "attrs",
@@ -427,10 +429,9 @@ public class SkylarkRuleClassFunctions {
         defaultValue = "False",
         doc =
             "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."
+                + "a <code>blaze run</code> command. See the "
+                + "<a href='../rules.$DOC_EXT#executable-rules-and-test-rules'>Rules page</a> for "
+                + "more information."
       ),
       @Param(
         name = "output_to_genfiles",