Update subrule documentation
PiperOrigin-RevId: 581944016
Change-Id: Iecad9c6933b269043b801571cb81f394e6bbb4ea
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java b/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java
index 50842d8..a9fca48 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkSubrule.java
@@ -70,7 +70,6 @@
*/
public class StarlarkSubrule implements StarlarkExportable, StarlarkCallable, StarlarkSubruleApi {
// TODO(hvd) this class is a WIP, will be implemented over many commits
- // TODO: b/293304174 - Fix all user-facing Starlark documentation
private final StarlarkFunction implementation;
private final ImmutableSet<ToolchainTypeRequirement> toolchains;
@@ -153,7 +152,6 @@
} else if (attribute.getType() == BuildType.LABEL_LIST) {
value = ruleContext.getRuleContext().getPrerequisites(attribute.getName());
} else if (attribute.getType() == BuildType.LABEL) {
- // TODO: b/293304174 - document this behavior
if (attribute.isSingleArtifact()) {
value = ruleContext.getRuleContext().getPrerequisiteArtifact(attribute.getName());
} else {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java
index 543fb1c..5d0b05c 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java
@@ -519,7 +519,7 @@
named = true,
defaultValue = "[]",
positional = false,
- doc = "Experimental, DO NOT USE!"),
+ doc = "Experimental: List of subrules used by this rule."),
},
useStarlarkThread = true)
StarlarkCallable rule(
@@ -739,7 +739,7 @@
named = true,
defaultValue = "[]",
positional = false,
- doc = "Experimental, DO NOT USE!")
+ doc = "Experimental: list of subrules used by this aspect.")
},
useStarlarkThread = true)
StarlarkAspectApi aspect(
@@ -815,7 +815,9 @@
@StarlarkMethod(
name = "subrule",
- doc = "experimental, DO NOT USE!",
+ doc =
+ "Constructs a new instance of a subrule. The result of this function must be stored in "
+ + "a global variable before it can be used.",
parameters = {
@Param(
name = "implementation",
@@ -829,7 +831,22 @@
named = true,
positional = false,
defaultValue = "{}",
- doc = "dictionary to declare all the (private) attributes of the subrule."),
+ doc =
+ "A dictionary to declare all the (private) attributes of the subrule. "
+ + "<p/>Subrules may only have private attributes that are label-typed (i.e. "
+ + "label or label-list). The resolved values corresponding to these labels are"
+ + " automatically passed by Bazel to the subrule's implementation function as"
+ + " named arguments (thus the implementation function is required to accept"
+ + " named parameters matching the attribute names). The types of these values"
+ + " will be: "
+ + "<ul><li><code>FilesToRunProvider</code> for label attributes with"
+ + " <code>executable=True</code></li>"
+ + "<li><code>File</code> for label attributes"
+ + " with <code>allow_single_file=True</code></li>"
+ + "<li><code>Target</code> for"
+ + " all other label attributes</li>"
+ + "<li><code>[Target]</code> for all label-list"
+ + " attributes</li></ul>"),
@Param(
name = "toolchains",
allowedTypes = {@ParamType(type = Sequence.class)},
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java
index e441090..12296f2 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkSubruleApi.java
@@ -19,5 +19,11 @@
import net.starlark.java.eval.StarlarkValue;
/** The interface for Starlark-defined subrules in the Build API. */
-@StarlarkBuiltin(name = "Subrule", category = DocCategory.BUILTIN, documented = false)
+@StarlarkBuiltin(
+ name = "Subrule",
+ category = DocCategory.BUILTIN,
+ doc =
+ "Experimental: a building block for writing rules with shared code. For more information,"
+ + " please see the subrule proposal:"
+ + " https://docs.google.com/document/d/1RbNC88QieKvBEwir7iV5zZU08AaMlOzxhVkPnmKDedQ")
public interface StarlarkSubruleApi extends StarlarkValue {}
