Improve "Common Attributes" section

Creates a separate section for attributes which are added to most build rules, but not implicitly added to Starlark rules. deps, data, and licenses are moved to that section.

srcs is also added to the new section, since I think that's as notable a naming convention to highlight as "deps" and "data".

The section on "deps" is updated to note:
* That "deps" generally should contain only specific rules and not files
* How "deps" generally varies between language specific rules
* The general relationship between "srcs" and "deps".

Also, a bit that says "deps" are always included in runfiles is removed. That's not even usually true. Though it may be true in some cases that source code is needed at runtime and therefore should be included in runfiles (this could be the case for build rules for some interpreted languages, for example), often source code is not needed at runtime and shouldn't be included in runfiles.

The section on "data" is updated to note:
* That generally "data" permits arbitrary dependencies
* That default outputs and runfiles from targets in data should be included in the runfiles of consumers
* The general relationship between "data" and "srcs"
* What Starlark rules need to do to handle data in their implementation functions

The remainder of the section is updated to:
* Consistently use "target" instead of "rule" to refer to rule targets. "Rule target" is unnecessary, file targets don't have attributes
* Use a consistent format the type of the attribute
* Consistently omit that optional list or dictionary attributes default to empty lists or dictionaries
* Use False instead of 0 for the default values of attributes whose type is "boolean"

And did a bit of copyediting.

A line from the introduction to the "common attributes" section that mentions it's an error to list the same label twice in a label-list attribute is pruned. That's true, but it seems misplaced here, it's not very related to the rest of this section.

"applicable_licenses" and "transitive_configs" are not yet documented.

RELNOTES: None.
PiperOrigin-RevId: 351577116

Author: Googler

src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java

@@ -246,6 +246,8 @@ private void processAttributeDocs(Iterable<RuleDocumentation> ruleDocEntries,
                 ruleDoc.addAttribute(PredefinedAttributes.TEST_ATTRIBUTES.get(attrName));
               } else if (PredefinedAttributes.COMMON_ATTRIBUTES.containsKey(attrName)) {
                 ruleDoc.addAttribute(PredefinedAttributes.COMMON_ATTRIBUTES.get(attrName));
+              } else if (PredefinedAttributes.TYPICAL_ATTRIBUTES.containsKey(attrName)) {
+                ruleDoc.addAttribute(PredefinedAttributes.TYPICAL_ATTRIBUTES.get(attrName));
               }
             }
           }

src/main/java/com/google/devtools/build/docgen/DocgenConsts.java

@@ -62,6 +62,7 @@ public class DocgenConsts {
 
   public static final String VAR_SECTION_STARLARK_BUILTIN = "SECTION_BUILTIN";
 
+  public static final String TYPICAL_ATTRIBUTES = "typical";
   public static final String COMMON_ATTRIBUTES = "common";
   public static final String TEST_ATTRIBUTES = "test";
   public static final String BINARY_ATTRIBUTES = "binary";

src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java

@@ -68,6 +68,9 @@ private void writeCommonDefinitionsPage(String outputDir, RuleLinkExpander expan
       throws IOException {
     Page page = TemplateEngine.newPage(DocgenConsts.COMMON_DEFINITIONS_TEMPLATE);
     page.add("expander", expander);
+    page.add(
+        "typicalAttributes",
+        expandCommonAttributes(PredefinedAttributes.TYPICAL_ATTRIBUTES, expander));
     page.add("commonAttributes",
         expandCommonAttributes(PredefinedAttributes.COMMON_ATTRIBUTES, expander));
     page.add("testAttributes",

src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java

@@ -42,19 +42,29 @@ public class PredefinedAttributes {
           "templates/attributes/test/local.html");
 
   /**
-   * List of common attributes documentation, relative to {@link com.google.devtools.build.docgen}.
+   * List of typical (defined by most rules, but not implicitly added to all rules) attributes
+   * documentation, relative to {@link com.google.devtools.build.docgen}.
    */
+  public static final ImmutableList<String> TYPICAL_ATTRIBUTES_DOCFILES =
+      ImmutableList.of(
+          "templates/attributes/typical/data.html",
+          "templates/attributes/typical/deps.html",
+          "templates/attributes/typical/licenses.html",
+          "templates/attributes/typical/srcs.html");
+
+  /**
+   * List of common (implicitly added to all rules) attributes documentation, relative to {@link
+   * com.google.devtools.build.docgen}.
+   */
+  // TODO(b/177233238): This should also document applicable_licenses and transitive_configs.
   public static final ImmutableList<String> COMMON_ATTRIBUTES_DOCFILES =
       ImmutableList.of(
           "templates/attributes/common/compatible_with.html",
-          "templates/attributes/common/data.html",
           "templates/attributes/common/deprecation.html",
-          "templates/attributes/common/deps.html",
           "templates/attributes/common/distribs.html",
           "templates/attributes/common/exec_compatible_with.html",
           "templates/attributes/common/exec_properties.html",
           "templates/attributes/common/features.html",
-          "templates/attributes/common/licenses.html",
           "templates/attributes/common/restricted_to.html",
           "templates/attributes/common/tags.html",
           "templates/attributes/common/target_compatible_with.html",
@@ -74,8 +84,7 @@ public class PredefinedAttributes {
 
   private static ImmutableMap<String, RuleDocumentationAttribute> generateAttributeMap(
       String commonType, ImmutableList<String> filenames) {
-    ImmutableMap.Builder<String, RuleDocumentationAttribute> builder =
-        ImmutableMap.<String, RuleDocumentationAttribute>builder();
+    ImmutableMap.Builder<String, RuleDocumentationAttribute> builder = ImmutableMap.builder();
     for (String filename : filenames) {
       String name = Files.getNameWithoutExtension(filename);
       try {
@@ -92,6 +101,9 @@ private static ImmutableMap<String, RuleDocumentationAttribute> generateAttribut
     return builder.build();
   }
 
+  public static final ImmutableMap<String, RuleDocumentationAttribute> TYPICAL_ATTRIBUTES =
+      generateAttributeMap(DocgenConsts.TYPICAL_ATTRIBUTES, TYPICAL_ATTRIBUTES_DOCFILES);
+
   public static final ImmutableMap<String, RuleDocumentationAttribute> COMMON_ATTRIBUTES =
       generateAttributeMap(DocgenConsts.COMMON_ATTRIBUTES, COMMON_ATTRIBUTES_DOCFILES);
 

src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java

@@ -54,6 +54,9 @@ public void generateDocumentation(List<String> inputDirs, String outputDir, Stri
     page.add("expander", expander);
 
     // Populate variables for Common Definitions section.
+    page.add(
+        "typicalAttributes",
+        expandCommonAttributes(PredefinedAttributes.TYPICAL_ATTRIBUTES, expander));
     page.add("commonAttributes",
         expandCommonAttributes(PredefinedAttributes.COMMON_ATTRIBUTES, expander));
     page.add("testAttributes",

src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html

@@ -7,20 +7,14 @@
 </p>
 
 <p>
-Command line arguments that bazel will pass to the target when it is executed
+Command line arguments that Bazel will passes to the target when it is executed
 either by the <code>run</code> command or as a test. These arguments are
 passed before the ones that are specified on the <code>bazel run</code> or
 <code>bazel test</code> command line.
 </p>
 
 <p>
 <em class="harmful">NOTE: The arguments are not passed when you run the target
-outside of bazel (for example, by manually executing the binary in
+outside of Bazel (for example, by manually executing the binary in
 <code>bazel-bin/</code>).</em>
 </p>
-
-<p>
-Most binary rules permit an <code>args</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.
-</p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html

@@ -13,6 +13,6 @@
 
 <p>
 <em class="harmful">NOTE: The environment variables are not set when you run the target
-outside of bazel (for example, by manually executing the binary in
+outside of Bazel (for example, by manually executing the binary in
 <code>bazel-bin/</code>).</em>
 </p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html

@@ -1,15 +1,15 @@
-<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
+<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional;
+  <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
-The list of environments this rule can be built for, in addition to
+The list of environments this target can be built for, in addition to
 default-supported environments.
 </p>
 
 <p>
-This is part of Bazel's soft-launched constraint system, which lets users
-declare which rules can and cannot depend on each other. For example,
-externally deployable binaries shouldn't depend on libraries with
-company-secret code. See
+This is part of Bazel's constraint system, which lets users declare which
+targets can and cannot depend on each other. For example, externally deployable
+binaries shouldn't depend on libraries with company-secret code. See
 <a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46">
 ConstraintSemantics</a> for details.
 </p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html

@@ -1,8 +1,8 @@
 <p><code>String; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
-An explanatory warning message associated with this rule.
-Typically this is used to notify users that a rule has become obsolete,
+An explanatory warning message associated with this target.
+Typically this is used to notify users that a target has become obsolete,
 or has become superseded by another rule, is private to a package, or is
 perhaps considered harmful for some reason. It is a good idea to include
 some reference (like a webpage, a bug number or example migration CLs) so
@@ -15,7 +15,7 @@
 This attribute has no effect on the way things are built, but it
 may affect a build tool's diagnostic output.  The build tool issues a
 warning when a rule with a <code>deprecation</code> attribute is
-depended upon by another rule.
+depended upon by a target in another package.
 </p>
 
 <p>
@@ -25,10 +25,10 @@
 </p>
 
 <p>
-If a deprecated rule depends on another deprecated rule, no warning
+If a deprecated target depends on another deprecated target, no warning
 message is issued.
 </p>
 
 <p>
-Once people have stopped using it, the package can be removed.
+Once people have stopped using it, the target can be removed.
 </p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html

@@ -1,7 +1,7 @@
 <p><code>List of strings; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
-  A list of distribution-method strings to be used for this particular build rule.
+  A list of distribution-method strings to be used for this particular target.
 
 This is part of a deprecated licensing API that Bazel no longer uses. Don't
 use this.

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html

@@ -1,11 +1,14 @@
-<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
+<p>
+<code>List of <a href="../build-ref.html#labels">labels</a>; optional;
+<a href="#configurable-attributes">nonconfigurable</a></code>
+</p>
 
 <p>
 A list of
 <code><a href="platform.html#constraint_value">constraint_values</a></code>
 that must be present in the execution platform for this target. This is in
 addition to any constraints already set by the rule type. Constraints are used
-to restrict the list of available execution platforms, see the description of
-  <a href="../toolchains.html#toolchain-resolution">toolchain resolution</a>
-  for details.
-</p>
+to restrict the list of available execution platforms. For more details, see
+the description of
+  <a href="../toolchains.html#toolchain-resolution">toolchain resolution</a>.
+  </p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html

@@ -1,4 +1,4 @@
-<p><code>Dictionary of strings. Default is an empty dictionary.</code></p>
+<p><code>Dictionary of strings; optional</code></p>
 
 <p> A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platform.html">platform</a> rule.</p>
 

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html

@@ -1,11 +1,11 @@
-<p><code>List of <i>features</i>. Default is the empty list.</code></p>
+<p><code>List of <i>feature</i> strings; optional</code></p>
 
 <p>A feature is string tag that can be enabled or disabled on a target. The
   meaning of a feature depends on the rule itself.</p>
 
 <p>This <code>features</code> attribute is combined with the <a href="${link
 package}">package</a> level <code>features</code> attribute. For example, if
-the features ["a", "b"] are enabled on the package level, and a rule
+the features ["a", "b"] are enabled on the package level, and a target's
 <code>features</code> attribute contains ["-a", "c"], the features enabled for the
 rule will be "b" and "c".
   <a href="https://github.com/bazelbuild/examples/blob/master/rules/features/BUILD">

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html

@@ -1,12 +1,13 @@
-<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
+<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional;
+  <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
-The list of environments this rule can be built for, <i>instead</i> of
+The list of environments this target can be built for, <i>instead</i> of
 default-supported environments.
 </p>
 
 <p>
-This is part of Bazel's soft-launched constraint system. See
+This is part of Bazel's constraint system. See
 <code><a href="#common.compatible_with">compatible_with</a></code>
 for details.
 </p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html

@@ -1,12 +1,11 @@
 <p>
-  <code>List of arbitrary text tags.  Tags may be any valid string; default is
-  the empty list; <a href="#configurable-attributes">nonconfigurable</a></code>
+  <code>List of strings; optional; <a href="#configurable-attributes">nonconfigurable</a></code>
 </p>
 
 <p>
   <i>Tags</i> can be used on any rule. <i>Tags</i> on test and
   <code>test_suite</code> rules are useful for categorizing the tests.
-  <i>Tags</i> on non-test rules are used to control sandboxed execution of
+  <i>Tags</i> on non-test targets are used to control sandboxed execution of
   <code>genrule</code>s and
 
 <a href="/versions/{{ site.version }}/skylark/index.html">Starlark</a>
@@ -15,9 +14,9 @@
 
 <p>
   Bazel modifies the behavior of its sandboxing code if it finds the following
-  keywords in the <code>tags</code> attribute of any test rule or
-  <code>genrule</code>, or the keys of <code>execution_requirements</code> for
-  any Starlark action.
+  keywords in the <code>tags</code> attribute of any test or <code>genrule</code>
+  target, or the keys of <code>execution_requirements</code> for any Starlark
+  action.
 </p>
 
 <ul>
@@ -111,4 +110,4 @@
 </ul>
 
 See <a href="../test-encyclopedia.html#tag-conventions">Tag Conventions</a> in the
-Test Encyclopedia for more conventions on tags attached to test rules.
+Test Encyclopedia for more conventions on tags attached to test targets.

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html

@@ -1,16 +1,15 @@
 <p>
-<code>List of <a href="../build-ref.html#labels">labels</a>; optional; default
-is the empty list</code>
+<code>List of <a href="../build-ref.html#labels">labels</a>; optional</code>
 </p>
 
 <p>
 A list of
 <code><a href="platform.html#constraint_value">constraint_value</a></code>s
 that must be present in the target platform for this target to be considered
-"compatible". This is in addition to any constraints already set by the rule
-type. If the target platform does not satisfy all listed constraints then the
-target is considered "incompatible". Incompatible targets are skipped for
-building and testing when the target pattern is expanded
+<em>compatible</em>. This is in addition to any constraints already set by the
+rule type. If the target platform does not satisfy all listed constraints then
+the target is considered <em>incompatible</em>. Incompatible targets are
+skipped for building and testing when the target pattern is expanded
 (e.g. `//...`, `:all`). When explicitly specified on the command line,
 incompatible targets cause Bazel to print an error and cause a build or test
 failure.

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html

@@ -1,4 +1,5 @@
-<p><code>Boolean; optional; default False except as noted; <a href="#configurable-attributes">nonconfigurable</a></code></p>
+<p><code>Boolean; optional; default False except for test and test suite targets;
+  <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
 If True, only testonly targets (such as tests) can depend on this target.

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html

@@ -1,11 +1,10 @@
 <p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
-  The set of targets whose <a href="${link make-variables}">Make variables</a> the rule is allowed
-  to access. These rules are either rules that provide
-  the <code>TemplateVariableInfo</code> provider or special targets for toolchain types built into
-Bazel.
-These include:
+  The set of targets whose <a href="${link make-variables}">Make variables</a> this target is
+  allowed to access. These targets are either instances of rules that provide
+  <code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These
+  include:
 
 <ul>
     <li><code>@bazel_tools//tools/cpp:current_cc_toolchain</code>
@@ -16,5 +15,6 @@
   Note that this is distinct from the concept of
     <a href="../toolchains.html#toolchain-resolution">toolchain resolution</a>
     that is used by rule implementations for platform-dependent configuration. You cannot use this
-  attribute to determine which specific cc_toolchain or java_toolchain a target will use.
+  attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a
+  target will use.
 </p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html

@@ -4,6 +4,7 @@
   otherwise; <a href="#configurable-attributes">nonconfigurable</a></code></p>
 
 <p>
-The <code>visibility</code> attribute on a rule controls whether the rule can
-be used by other packages. See the documentation for <a href="../visibility.md">visibility</a>.
+The <code>visibility</code> attribute on a target controls whether the target
+can be used in other packages. See the documentation for
+<a href="../visibility.md">visibility</a>.
 </p>