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

2 files changed, 24 insertions, 17 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java b/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java
index 7e264670b8..dcc5080ca6 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java
@@ -63,10 +63,16 @@ import javax.annotation.concurrent.GuardedBy;
   name = "Action",
   category = SkylarkModuleCategory.BUILTIN,
   doc =
-      "An action created on a <a href=\"ctx.html\">ctx</a> object. You can retrieve these "
-          + "using the <a href=\"globals.html#Actions\">Actions</a> provider. Some fields are only "
-          + "applicable for certain kinds of actions. Fields that are inapplicable are set to "
-          + "<code>None</code>."
+      "An action created during rule analysis."
+          + "<p>This object is visible for the purpose of testing, and may be obtained from an "
+          + "<a href=\"globals.html#Actions\">Actions</a> provider. It is normally not necessary "
+          + "to access `Action` objects or their fields within a rule's implementation function. "
+          + "You may instead want to see the "
+          + "<a href='../rules.$DOC_EXT#actions'>Rules page</a> for a general discussion of how to "
+          + "use actions when defining custom rules, or the <a href='actions.html'>API reference"
+          + "</a> for creating actions."
+          + "<p>Some fields of this object are only applicable for certain kinds of actions. "
+          + "Fields that are inapplicable are set to <code>None</code>."
 )
 public abstract class AbstractAction implements Action, SkylarkValue {
   /**
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",