Fix up documentation for Actions API

--
MOS_MIGRATED_REVID=139569372

7 files changed, 43 insertions, 23 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/BUILD b/src/main/java/com/google/devtools/build/docgen/BUILD
index 142f806cd8..ff5c5d21d1 100644
--- a/src/main/java/com/google/devtools/build/docgen/BUILD
+++ b/src/main/java/com/google/devtools/build/docgen/BUILD
@@ -15,6 +15,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib:java-rules",
         "//src/main/java/com/google/devtools/build/lib:packages",
         "//src/main/java/com/google/devtools/build/lib:skylarkinterface",
+        "//src/main/java/com/google/devtools/build/lib/actions",
         "//src/main/java/com/google/devtools/build/lib/rules/apple",
         "//src/main/java/com/google/devtools/build/lib/rules/cpp",
         "//src/main/java/com/google/devtools/common/options",
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
index 2ffb83517b..d8e98223e7 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -19,6 +19,7 @@ import com.google.common.collect.ImmutableMap;
 import com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkJavaMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkModuleDoc;
+import com.google.devtools.build.lib.actions.AbstractAction;
 import com.google.devtools.build.lib.analysis.TransitiveInfoCollection;
 import com.google.devtools.build.lib.rules.SkylarkModules;
 import com.google.devtools.build.lib.rules.SkylarkRuleContext;
@@ -189,6 +190,8 @@ final class SkylarkDocumentationCollector {
     collectBuiltinModule(modules, SkylarkRuleContext.class);
     collectBuiltinModule(modules, TransitiveInfoCollection.class);
 
+    collectBuiltinModule(modules, AbstractAction.class);
+
     collectBuiltinModule(modules, AppleConfiguration.class);
     collectBuiltinModule(modules, CppConfiguration.class);
     collectBuiltinModule(modules, JavaConfiguration.class);
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 69bcac0355..dd4dc97169 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
@@ -29,6 +29,7 @@ import com.google.devtools.build.lib.events.Event;
 import com.google.devtools.build.lib.events.EventHandler;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkValue;
 import com.google.devtools.build.lib.syntax.Printer;
 import com.google.devtools.build.lib.syntax.SkylarkDict;
@@ -52,8 +53,12 @@ import javax.annotation.Nullable;
 @Immutable @ThreadSafe
 @SkylarkModule(
     name = "Action",
-    doc = "Base class for actions.",
-    documented = false)
+    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>."
+)
 public abstract class AbstractAction implements Action, SkylarkValue {
 
   /**
@@ -508,7 +513,9 @@ public abstract class AbstractAction implements Action, SkylarkValue {
   @SkylarkCallable(
       name = "argv",
       doc = "For actions created by <a href=\"ctx.html#action\">ctx.action()</a>, an immutable "
-          + "list of the command line arguments. For all other actions, None.",
+          + "list of the arguments for the command line to be executed. Note that when using the "
+          + "shell (i.e., when <a href=\"ctx.html#action.executable\">executable</a> is not set), "
+          + "the first two arguments will be the shell path and <code>\"-c\"</code>.",
       structField = true,
       allowReturnNones = true)
   public SkylarkList<String> getSkylarkArgv() {
@@ -519,7 +526,7 @@ public abstract class AbstractAction implements Action, SkylarkValue {
       name = "content",
       doc = "For actions created by <a href=\"ctx.html#file_action\">ctx.file_action()</a> or "
           + "<a href=\"ctx.html#template_action\">ctx.template_action()</a>, the contents of the "
-          + "file to be written. For all other actions, None.",
+          + "file to be written.",
       structField = true,
       allowReturnNones = true)
   public String getSkylarkContent() throws IOException {
@@ -528,8 +535,8 @@ public abstract class AbstractAction implements Action, SkylarkValue {
 
   @SkylarkCallable(
       name = "substitutions",
-      doc = "For actions created by <a href=\"ctx#template_action\">ctx.template_action()</a>, "
-          + "an immutable dict holding the substitution mapping. For all other actions, None.",
+      doc = "For actions created by <a href=\"ctx.html#template_action\">"
+          + "ctx.template_action()</a>, an immutable dict holding the substitution mapping.",
       structField = true,
       allowReturnNones = true)
   public SkylarkDict<String, String> getSkylarkSubstitutions() {
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/ActionsProvider.java b/src/main/java/com/google/devtools/build/lib/analysis/ActionsProvider.java
index c0c6adb98a..9f3a882a4a 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/ActionsProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/ActionsProvider.java
@@ -25,7 +25,7 @@ import java.util.Map;
  * This provides a view over the actions that were created during the analysis of a rule
  * (not including actions for its transitive dependencies).
  */
-public final class ActionsProvider{
+public final class ActionsProvider {
 
   public static final SkylarkClassObjectConstructor ACTIONS_PROVIDER =
       SkylarkClassObjectConstructor.createNative("Actions");
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
index def3f5220d..c78aa186ab 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
@@ -207,10 +207,17 @@ public class SkylarkRuleClassFunctions {
   // configured BaseFunction, rather than defining a new BuiltinFunction. This should wait for
   // better support from the Skylark/Java interface, or perhaps support for first-class modules.
   @SkylarkSignature(name = "Actions", returnType = SkylarkClassObjectConstructor.class, doc =
-      "Provides access to the actions generated by a rule. This is designed for testing rules, "
-          + "and should not be accessed outside of test logic. This provider is only available for "
-          + "targets generated by rules marked with <pre class=\"language-python\">"
-          + "_skylark_testable=True</pre>."
+      "<i>(Note: This is a provider type. Don't instantiate it yourself; use it to retrieve a "
+          + "provider object from a <a href=\"Target.html\">Target</a>.)</i>"
+          + "<br/><br/>"
+          + "Provides access to the <a href=\"Action.html\">actions</a> generated by a rule. There "
+          + "is one field, <code>by_file</code>, which is a dictionary from an output of the rule "
+          + "to its corresponding generating action. "
+          + "<br/><br/>"
+          + "This is designed for testing rules, and should not be accessed outside of test logic. "
+          + "This provider is only available for targets generated by rules that have "
+          + "<a href=\"globals.html#rule._skylark_testable\">_skylark_testable</a> set to "
+          + "<code>True</code>."
   )
   private static final SkylarkClassObjectConstructor actions = ActionsProvider.ACTIONS_PROVIDER;
 
@@ -330,13 +337,13 @@ public class SkylarkRuleClassFunctions {
         type = Boolean.class,
         defaultValue = "False",
         doc =
-            "<i>(Experimental)</i> "
+            "<i>(Experimental)</i><br/><br/>"
                 + "If true, this rule will expose its actions for inspection by rules that depend "
-                + "on it via an <a href=\"ActionsSkylarkApiProvider.html\">actions</a> provider."
+                + "on it via an <a href=\"globals.html#Actions\">Actions</a> provider. "
                 + "The provider is also available to the rule itself by calling "
-                + "<code>ctx.created_actions()</code>."
-                + ""
-                + "<p>This should only be used for testing the analysis-time behavior of Skylark "
+                + "<a href=\"ctx.html#created_actions\">ctx.created_actions()</a>."
+                + "<br/><br/>"
+                + "This should only be used for testing the analysis-time behavior of Skylark "
                 + "rules. This flag may be removed in the future."
       )
     },
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
index 50fe8510cf..b68130d15e 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
@@ -435,14 +435,15 @@ public final class SkylarkRuleContext {
   }
 
   @SkylarkCallable(name = "created_actions",
-      doc = "For rules marked <code>_skylark_testable=True</code>, this returns an "
-          + "<a href=\"ActionsSkylarkApiProvider.html\">actions</a> provider representing all "
-          + "actions created so far for the current rule. For all other rules, returns None. "
+      doc = "For rules with <a href=\"globals.html#rule._skylark_testable\">_skylark_testable"
+          + "</a> set to <code>True</code>, this returns an "
+          + "<a href=\"globals.html#Actions\">Actions</a> provider representing all actions "
+          + "created so far for the current rule. For all other rules, returns <code>None</code>. "
           + "Note that the provider is not updated when subsequent actions are created, so you "
           + "will have to call this function again if you wish to inspect them. "
-          + ""
-          + "<p>This is intended to help test rule-implementation helper functions that take in a "
-          + "<a href=\"ctx.html\">ctx</a> object and create actions for it.")
+          + "<br/><br/>"
+          + "This is intended to help write tests for rule-implementation helper functions, which "
+          + "may take in a<code>ctx</code> object and create actions on it.")
   public Object createdActions() {
     if (ruleContext.getRule().getRuleClassObject().isSkylarkTestable()) {
       return ActionsProvider.create(
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
index 166a4b7ba4..355f8f0da9 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
@@ -338,7 +338,8 @@ public class SkylarkRuleImplementationFunctions {
       "Expands all <code>$(location ...)</code> templates in the given string by replacing "
       + "<code>$(location //x)</code> with the path of the output file of target //x. "
       + "Expansion only works for labels that point to direct dependencies of this rule or that "
-      + "are explicitly listed in the optional argument <code>targets</code>.<br/>"
+      + "are explicitly listed in the optional argument <code>targets</code>. "
+      + "<br/><br/>"
       + "<code>$(location ...)</code> will cause an error if the referenced target has multiple "
       + "outputs. In this case, please use <code>$(locations ...)</code> since it produces a space-"
       + "separated list of output paths. It can be safely used for a single output file, too.",