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>