Improve DefaultInfo Starlark documentation.
Fixes #3015.
RELNOTES: None.
PiperOrigin-RevId: 311214959
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/DefaultInfoApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/DefaultInfoApi.java
index 9622e18..28b0015 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/DefaultInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/DefaultInfoApi.java
@@ -32,7 +32,7 @@
doc =
"A provider that gives general information about a target's direct and transitive files. "
+ "Every rule type has this provider, even if it is not returned explicitly by the "
- + "rule's implementation function."
+ + "rule's implementation function. "
+ "Each <code>DefaultInfo</code> instance has the following fields: "
+ "<ul>"
+ "<li><code>files</code>"
@@ -40,9 +40,15 @@
+ "<li><code>data_runfiles</code>"
+ "<li><code>default_runfiles</code>"
+ "</ul>"
- + "See the <a href='../rules.$DOC_EXT'>rules</a> page for more information.")
+ + "See the <a href='../rules.$DOC_EXT'>rules</a> page for extensive guides on how to "
+ + "use this provider.")
public interface DefaultInfoApi extends StructApi {
+ static final String DEPRECATED_RUNFILES_PARAMETER_WARNING =
+ "<p><b>It is recommended that you avoid using this parameter (see "
+ + "<a href='../rules.$DOC_EXT#runfiles-features-to-avoid'>"
+ + "\"runfiles features to avoid\"</a>)</b></p> ";
+
@SkylarkCallable(
name = "files",
doc =
@@ -65,21 +71,23 @@
@SkylarkCallable(
name = "data_runfiles",
- doc = "the files that are added to the runfiles of a "
- + "target that depend on the rule via the <code>data</code> attribute.",
+ doc =
+ "runfiles descriptor describing the files that this target needs when run in the "
+ + "condition that it is a <code>data</code> dependency attribute. Under most "
+ + "circumstances, use the <code>default_runfiles</code> parameter instead. "
+ + "See <a href='../rules.$DOC_EXT#runfiles-features-to-avoid'>"
+ + "\"runfiles features to avoid\"</a> for details. ",
structField = true,
- allowReturnNones = true
- )
+ allowReturnNones = true)
RunfilesApi getDataRunfiles();
@SkylarkCallable(
name = "default_runfiles",
- doc = "the files that are added to the runfiles of "
- + "a target that depend on the rule via anything but the <code>data</code> "
- + "attribute.",
+ doc =
+ "runfiles descriptor describing the files that this target needs when run "
+ + "(via the <code>run</code> command or as a tool dependency).",
structField = true,
- allowReturnNones = true
- )
+ allowReturnNones = true)
RunfilesApi getDefaultRunfiles();
/** Provider for {@link DefaultInfoApi}. */
@@ -111,8 +119,8 @@
defaultValue = "None",
noneable = true,
doc =
- "set of files acting as both the "
- + "<code>data_runfiles</code> and <code>default_runfiles</code>."),
+ "runfiles descriptor describing the files that this target needs when run "
+ + "(via the <code>run</code> command or as a tool dependency)."),
@Param(
name = "data_runfiles",
type = RunfilesApi.class,
@@ -121,8 +129,9 @@
defaultValue = "None",
noneable = true,
doc =
- "the files that are added to the runfiles of a "
- + "target that depend on the rule via the <code>data</code> attribute."),
+ DEPRECATED_RUNFILES_PARAMETER_WARNING
+ + "runfiles descriptor describing the runfiles this target needs to run "
+ + "when it is a dependency via the <code>data</code> attribute."),
@Param(
name = "default_runfiles",
type = RunfilesApi.class,
@@ -131,9 +140,10 @@
defaultValue = "None",
noneable = true,
doc =
- "the files that are added to the runfiles of "
- + "a target that depend on the rule via anything but the <code>data</code> "
- + "attribute."),
+ DEPRECATED_RUNFILES_PARAMETER_WARNING
+ + "runfiles descriptor describing the runfiles this target needs to run "
+ + "when it is a dependency via any attribute other than the "
+ + "<code>data</code> attribute."),
@Param(
name = "executable",
type = FileApi.class,
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java
index cb4609d..510e603 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java
@@ -29,7 +29,8 @@
"A container of information regarding a set of files required at runtime execution. This"
+ " object should be passed via <a href=\"DefaultInfo.html\">DefaultInfo</a> in order"
+ " to tell the build system about the runfiles needed by the outputs produced by the"
- + " rule. See <a href=\"../rules.html#runfiles\">runfiles guide</a> for details.")
+ + " rule. "
+ + "<p>See <a href=\"../rules.html#runfiles\">runfiles guide</a> for details.")
public interface RunfilesApi extends StarlarkValue {
@SkylarkCallable(
