diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build')
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.", |