diff options
Diffstat (limited to 'src/main/java/com')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java | 14 | ||||
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java | 27 |
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", |