Clarify attr documentation

Fixes #5335

RELNOTES: None
PiperOrigin-RevId: 203148338

1 files changed, 58 insertions, 38 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkAttrApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkAttrApi.java
index edc3fb8165..1da54ba761 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkAttrApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkAttrApi.java
@@ -39,17 +39,44 @@ import com.google.devtools.build.lib.syntax.UserDefinedFunction;
     namespace = true,
     category = SkylarkModuleCategory.BUILTIN,
     doc =
-        "Module for creating new attributes. "
-            + "They are only for use with <a href=\"globals.html#rule\">rule</a> or "
-            + "<a href=\"globals.html#aspect\">aspect</a>. "
-            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
-            + "attributes/printer.bzl\">See example of use</a>.")
+        "This is a top-level module for defining the attribute schemas of a rule or aspect. Each "
+            + "function returns an object representing the schema of a single attribute. These "
+            + "objects are used as the values of the <code>attrs</code> dictionary argument of "
+            + "<a href=\"globals.html#rule\"><code>rule()</code></a> and "
+            + "<a href=\"globals.html#aspect\"><code>aspect()</code></a>."
+            + ""
+            + "<p>See the Rules page for more on "
+            + "<a href='../rules.$DOC_EXT#attributes'>defining</a> and "
+            + "<a href='../rules.$DOC_EXT#implementation-function'>using</a> attributes.")
 public interface SkylarkAttrApi extends SkylarkValue {
 
+  // dependency and output attributes
+  static final String LABEL_PARAGRAPH =
+      "<p>This attribute contains <a href='Label.html'><code>Label</code></a> values. If a string "
+          + "is supplied in place of a <code>Label</code>, it will be converted using the "
+          + "<a href='Label.html#Label'>label constructor</a>. The relative parts of the label "
+          + "path, including the (possibly renamed) repository, are resolved with respect to the "
+          + "instantiated target's package.";
+
+  // attr.label, attr.label_list, attr.label_keyed_string_dict
+  static final String DEPENDENCY_ATTR_TEXT =
+      LABEL_PARAGRAPH
+          + "<p>At analysis time (within the rule's implementation function), when retrieving the "
+          + "attribute value from <code>ctx.attr</code>, labels are replaced by the corresponding "
+          + "<a href='Target.html'><code>Target</code></a>s. This allows you to access the "
+          + "providers of the currrent target's dependencies.";
+
+  // attr.output, attr.output_list
+  static final String OUTPUT_ATTR_TEXT =
+      LABEL_PARAGRAPH
+          + "<p>At analysis time, the corresponding <a href='File.html'><code>File</code></a> can "
+          + "be retrieved using <code>ctx.outputs</code>.";
+
   static final String ALLOW_FILES_ARG = "allow_files";
   static final String ALLOW_FILES_DOC =
-      "Whether File targets are allowed. Can be True, False (default), or a list of file "
-          + "extensions that are allowed (for example, <code>[\".cc\", \".cpp\"]</code>).";
+      "Whether <code>File</code> targets are allowed. Can be <code>True</code>, <code>False</code> "
+          + "(default), or a list of file extensions that are allowed (for example, "
+          + "<code>[\".cc\", \".cpp\"]</code>).";
 
   static final String ALLOW_RULES_ARG = "allow_rules";
   static final String ALLOW_RULES_DOC =
@@ -62,6 +89,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
           + "attribute.";
 
   static final String CONFIGURATION_ARG = "cfg";
+  // TODO(bazel-team): Update when new Skylark-based configuration framework is implemented.
   static final String CONFIGURATION_DOC =
       "<a href=\"../rules.$DOC_EXT#configurations\">Configuration</a> of the attribute. It can be "
           + "either <code>\"host\"</code> or <code>\"target\"</code>.";
@@ -76,7 +104,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   static final String EXECUTABLE_ARG = "executable";
   static final String EXECUTABLE_DOC =
-      "True if the label has to be executable. This means the label must refer to an "
+      "True if the dependency has to be executable. This means the label must refer to an "
           + "executable file, or to a rule that outputs an executable file. Access the label "
           + "with <code>ctx.executable.&lt;attribute_name&gt;</code>.";
 
@@ -88,7 +116,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   static final String NON_EMPTY_ARG = "non_empty";
   static final String NON_EMPTY_DOC =
-      "True if the attribute must not be empty. Deprecated: Use allow_empty instead.";
+      "True if the attribute must not be empty. Deprecated: Use <code>allow_empty</code> instead.";
 
   static final String ALLOW_EMPTY_ARG = "allow_empty";
   static final String ALLOW_EMPTY_DOC = "True if the attribute can be empty.";
@@ -110,7 +138,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   @SkylarkCallable(
       name = "int",
-      doc = "Creates an attribute of type int.",
+      doc = "Creates a schema for an integer attribute.",
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -158,7 +186,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   @SkylarkCallable(
       name = "string",
-      doc = "Creates an attribute of type <a href=\"string.html\">string</a>.",
+      doc = "Creates a schema for a string attribute.",
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -206,11 +234,8 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "label",
       doc =
-          "Creates an attribute of type <a href=\"Target.html\">Target</a> which is the target "
-              + "referred to by the label. "
-              + "It is the only way to specify a dependency to another target. "
-              + "If you need a dependency that the user cannot overwrite, "
-              + "<a href=\"../rules.$DOC_EXT#private-attributes\">make the attribute private</a>.",
+          "Creates a schema for a label attribute. This is a dependency attribute."
+              + DEPENDENCY_ATTR_TEXT,
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -335,8 +360,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "string_list",
       doc =
-          "Creates an attribute which is a <a href=\"list.html\">list</a> of "
-              + "<a href=\"string.html\">strings</a>.",
+          "Creates a schema for a list-of-strings attribute.",
       parameters = {
         @Param(
             name = MANDATORY_ARG,
@@ -388,7 +412,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   @SkylarkCallable(
       name = "int_list",
-      doc = "Creates an attribute which is a <a href=\"list.html\">list</a> of ints.",
+      doc = "Creates a schema for a list-of-integers attribute.",
       parameters = {
         @Param(
             name = MANDATORY_ARG,
@@ -441,9 +465,8 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "label_list",
       doc =
-          "Creates an attribute which is a <a href=\"list.html\">list</a> of type "
-              + "<a href=\"Target.html\">Target</a> which are specified by the labels in the list. "
-              + "See <a href=\"attr.html#label\">label</a> for more information.",
+          "Creates a schema for a list-of-labels attribute. This is a dependency attribute."
+              + DEPENDENCY_ATTR_TEXT,
       parameters = {
         @Param(
             name = ALLOW_EMPTY_ARG,
@@ -556,10 +579,9 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "label_keyed_string_dict",
       doc =
-          "Creates an attribute which is a <a href=\"dict.html\">dict</a>. Its keys are type "
-              + "<a href=\"Target.html\">Target</a> and are specified by the label keys of the "
-              + "input dict. Its values are <a href=\"string.html\">strings</a>. See "
-              + "<a href=\"attr.html#label\">label</a> for more information.",
+          "Creates a schema for an attribute holding a dictionary, where the keys are labels and "
+              + "the values are strings. This is a dependency attribute."
+              + DEPENDENCY_ATTR_TEXT,
       parameters = {
         @Param(
             name = ALLOW_EMPTY_ARG,
@@ -672,7 +694,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   @SkylarkCallable(
       name = "bool",
-      doc = "Creates an attribute of type bool.",
+      doc = "Creates a schema for a boolean attribute.",
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -708,9 +730,8 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "output",
       doc =
-          "Creates an attribute of type output. "
-              + "The user provides a file name (string) and the rule must create an action that "
-              + "generates the file.",
+          "Creates a schema for an output (label) attribute."
+              + OUTPUT_ATTR_TEXT,
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -747,8 +768,8 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "output_list",
       doc =
-          "Creates an attribute which is a <a href=\"list.html\">list</a> of outputs. "
-              + "See <a href=\"attr.html#output\">output</a> for more information.",
+          "Creates a schema for a list-of-outputs attribute."
+              + OUTPUT_ATTR_TEXT,
       parameters = {
         @Param(
             name = ALLOW_EMPTY_ARG,
@@ -803,8 +824,8 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "string_dict",
       doc =
-          "Creates an attribute of type <a href=\"dict.html\">dict</a>, mapping from "
-              + "<a href=\"string.html\">string</a> to <a href=\"string.html\">string</a>.",
+          "Creates a schema for an attribute holding a dictionary, where the keys and values are "
+              + "strings.",
       parameters = {
         @Param(
             name = ALLOW_EMPTY_ARG,
@@ -859,9 +880,8 @@ public interface SkylarkAttrApi extends SkylarkValue {
   @SkylarkCallable(
       name = "string_list_dict",
       doc =
-          "Creates an attribute of type <a href=\"dict.html\">dict</a>, mapping from "
-              + "<a href=\"string.html\">string</a> to <a href=\"list.html\">list</a> of "
-              + "<a href=\"string.html\">string</a>.",
+          "Creates a schema for an attribute holding a dictionary, where the keys are strings and "
+              + "the values are lists of strings.",
       parameters = {
         @Param(
             name = ALLOW_EMPTY_ARG,
@@ -915,7 +935,7 @@ public interface SkylarkAttrApi extends SkylarkValue {
 
   @SkylarkCallable(
       name = "license",
-      doc = "Creates an attribute of type license.",
+      doc = "Creates a schema for a license attribute.",
       // TODO(bazel-team): Implement proper license support for Skylark.
       parameters = {
         // TODO(bazel-team): ensure this is the correct default value