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
diff --git a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
index 552976c..a7438ad 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
@@ -246,6 +246,8 @@
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));
}
}
}
diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
index af957ff..19a4ae7 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -62,6 +62,7 @@
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";
diff --git a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
index 9bbdf63..d930041 100644
--- a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
@@ -68,6 +68,9 @@
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",
diff --git a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java
index d839cca..e0f8608 100644
--- a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java
+++ b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java
@@ -42,19 +42,29 @@
"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 @@
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 @@
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);
diff --git a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
index 883b141..346cc33 100644
--- a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
@@ -54,6 +54,9 @@
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",
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html
index 01cb9c7..aa17f6d 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html
@@ -7,7 +7,7 @@
</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.
@@ -15,12 +15,6 @@
<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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html
index 80cb86b..8885781 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html
+++ b/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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html
index 16fc1fe..3beb7ee 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html
+++ b/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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html
deleted file mode 100644
index 5be4ef2..0000000
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html
+++ /dev/null
@@ -1,20 +0,0 @@
-<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
-
-<p>
-The list of files needed by this rule at runtime.
-</p>
-
-<p>
-Targets named in the <code>data</code> attribute will appear in
-the <code>*.runfiles</code> area of this rule, if it has one. This
-may include data files needed by a binary or library, or other
-programs needed by it. See the
-<a href="../build-ref.html#data">data dependencies</a> section for more
-information about how to depend on and use data files.
-</p>
-
-<p>
-Almost all rules permit a <code>data</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.
-</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html
index abd667d..9ee89e4 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html
deleted file mode 100644
index 806e3de..0000000
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html
+++ /dev/null
@@ -1,32 +0,0 @@
-<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
-
-<p>
-A list of dependencies of this rule.
-</p>
-
-<p>
-The precise semantics of what it means for this rule to depend on
-another using <code>deps</code> are specific to the kind of this rule,
-and the rule-specific documentation below goes into more detail.
-At a minimum, though, the targets named via <code>deps</code> will
-appear in the <code>*.runfiles</code> area of this rule, if it has
-one.
-</p>
-
-<p>
-Most often, a <code>deps</code> dependency is used to allow one
-module to use symbols defined in another module written in the
-same programming language and separately compiled. Cross-language
-dependencies are also permitted in many cases: for example,
-a <code>java_library</code> rule may depend on C++ code in
-a <code>cc_library</code> rule, by declaring the latter in
-the <code>deps</code> attribute. See the definition
-of <a href="../build-ref.html#deps">dependencies</a> for more
-information.
-</p>
-
-<p>
-Almost all rules permit a <code>deps</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.
-</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html
index cd468dd..c54f7fc 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.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.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html
index a920e6a..c027e39 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html
index ae6f009..9d3d73a 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html
index 5ac9dd9..9358816 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.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">
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html
index fb0ece4..c3c2e5b 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
index f7a1fde..4ffcbc9 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.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.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html
index c65186a..5e698f9 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.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.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html
index 7c38715..736e49e 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.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.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html
index be89334..645337d 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html
index 749b02a..ab95f54 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.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>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html
index 7dab0d9..c384583 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html
@@ -3,10 +3,10 @@
<a href="${link make-variables}">"Make variable"</a> substitution, and
<a href="#sh-tokenization">Bourne shell tokenization</a></code></p>
-<p>Add these arguments to the <code>--test_arg</code>
-when executed by <code>bazel test</code>.</p>
+<p>Command line arguments that Bazel passes to the target when it is
+executed with <code>bazel test</code>.
<p>
-These arguments are passed before the <code>--test_arg</code> values
+These arguments are passed before any <code>--test_arg</code> values
specified on the <code>bazel test</code> command line.
</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html
index a2c8366..22cceb4 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html
@@ -1,4 +1,4 @@
-<p><code>List of strings; optional</p>
+<p><code>List of strings; optional</code></p>
<p>Specifies additional environment variables to inherit from the
external environment when the test is executed by <code>bazel test</code>.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html
index 3447010..6fc8590 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html
@@ -1,12 +1,12 @@
-<p><code>Boolean; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
+<p><code>Boolean; optional; default False; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p>
Marks test as flaky.
</p>
<p>
-If set, executes the test up to 3 times before being declared as failed.
-By default this attribute is set to 0 and test is considered to be stable.
-Note, that use of this attribute is generally discouraged - we do prefer
-all tests to be stable.
+If set, executes the test up to three times, marking it as failed only if it
+fails each time. By default, this attribute is set to False and the test is
+executed only once. Note, that use of this attribute is generally discouraged -
+tests should pass reliably when their assertions are upheld.
</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html
index 17d2683..a6e8c0e 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html
@@ -1,7 +1,6 @@
-<p><code>Boolean; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
+<p><code>Boolean; default False; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p>Forces the test to be run locally, without sandboxing.</p>
-<p>By default this attribute is set to 0 and the default testing strategy is
-used. This is equivalent to providing "local" as a tag
+<p>Setting this to True is equivalent to providing "local" as a tag
(<code>tags=["local"]</code>).</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html
index 2e7b403..c9af3c9 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html
@@ -1,5 +1,4 @@
-<p>Non-negative integer less than or equal to 50;
-optional</p>
+<p><code>Non-negative integer less than or equal to 50; optional</code></p>
<p>Specifies the number of parallel shards
to use to run the test.</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html
new file mode 100644
index 0000000..e86ab04
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html
@@ -0,0 +1,26 @@
+<a name="common.data"></a>
+<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
+
+<p>
+Files needed by this rule at runtime. May list file or rule targets. Generally
+allows any target.
+</p>
+
+<p>
+The default outputs and runfiles of targets in the <code>data</code> attribute
+should appear in the <code>*.runfiles</code> area of any executable which is
+output by or has a runtime dependency on this target. This may include data
+files or binaries used when this target's
+<a href="#typical.srcs"><code>srcs</code></a> are executed. See the
+<a href="../build-ref.html#data">data dependencies</a> section for more
+information about how to depend on and use data files.
+</p>
+
+<p>
+New rules should define a <code>data</code> attribute if they process
+inputs which might use other inputs at runtime. Rules' implementation functions
+must also <a href="../skylark/rules.html#runfiles">populate the target's
+runfiles</a> from the outputs and runfiles of any <code>data</code> attribute,
+as well as runfiles from any dependency attribute which provides either
+source code or runtime dependencies.
+</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html
new file mode 100644
index 0000000..6efe4e6
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html
@@ -0,0 +1,31 @@
+<a name="common.deps"></a>
+<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
+
+<p>
+Dependencies for this target. Generally should only list rule targets. (Though
+some rules permit files to be listed directly in <code>deps</code>, this
+should be avoided when possible.)
+</p>
+
+<p>
+Language-specific rules generally limit the listed targets to those with
+specific <a href="../skylark/rules.html#providers">providers</a>.
+</p>
+
+<p>
+The precise semantics of what it means for a target to depend on another using
+<code>deps</code> are specific to the kind of rule, and the rule-specific
+documentation goes into more detail. For rules which process source code,
+<code>deps</code> generally specifies code dependencies used by the code in
+<a href="#typical.srcs"><code>srcs</code></a>.
+</p>
+
+<p>
+Most often, a <code>deps</code> dependency is used to allow one module to use
+symbols defined in another module written in the same programming language and
+separately compiled. Cross-language dependencies are also permitted in many
+cases: For example, a <code>java_library</code> target may depend on C++ code
+in a <code>cc_library</code> target, by listing the latter in the
+<code>deps</code> attribute. See the definition of
+<a href="../build-ref.html#deps">dependencies</a> for more information.
+</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/licenses.html
similarity index 86%
rename from src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html
rename to src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/licenses.html
index d839299..ca28662 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/licenses.html
@@ -1,7 +1,8 @@
+<a name="common.licenses"></a>
<p><code>List of strings; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p>
- A list of license-type strings to be used for this particular build rule.
+ A list of license-type 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.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html
new file mode 100644
index 0000000..9b7b1ad
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html
@@ -0,0 +1,13 @@
+<p><code>List of <a href="../build-ref.html#labels">labels</a>;
+ optional</code></p>
+
+<p>
+Files processed or included by this rule. Generally lists files directly, but
+may list rule targets (like <code>filegroup</code> or <code>genrule</code>) to
+include their default outputs.
+</p>
+
+<p>
+Language-specific rules often require that the listed files have particular
+file extensions.
+</p>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
index 08c69a0..717db6d 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
@@ -11,7 +11,7 @@
<h1 id="common-definitions">Common definitions</h1>
<p>This section defines various terms and concepts that are common to
-many functions or build rules below.
+many functions or build rules.
</p>
#if (!$singlePage)
@@ -20,6 +20,7 @@
<ul>
<li><a href="#sh-tokenization">Bourne shell tokenization</a></li>
<li><a href="#label-expansion">Label Expansion</a></li>
+ <li><a href="#typical-attributes">Typical attributes defined by most build rules</a></li>
<li><a href="#common-attributes">Attributes common to all build rules</a></li>
<li><a href="#common-attributes-tests">Attributes common to all test rules (*_test)</a></li>
<li><a href="#common-attributes-binaries">Attributes common to all binary rules (*_binary)</a></li>
@@ -68,8 +69,6 @@
specifics.
</p>
-<h2 id="common-attributes">Attributes common to all build rules</h2>
-
#macro(commonAttributeDoc $type $attributeMap)
<table class="table table-condensed table-bordered table-params">
<colgroup>
@@ -93,9 +92,18 @@
</table>
#end
-<p>This section describes attributes that are common to all build rules.<br/>
-Please note that it is an error to list the same label twice in a list of
-labels attribute.
+<h2 id="typical-attributes">Typical attributes defined by most build rules</h2>
+
+<p>This section describes attributes that are defined by many build rules,
+but not all.
+</p>
+
+#commonAttributeDoc("typical" $typicalAttributes)
+
+<h2 id="common-attributes">Attributes common to all build rules</h2>
+
+<p>This section describes attributes that are implicitly added to all build
+rules.
</p>
#commonAttributeDoc("common" $commonAttributes)
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
index a8faef4..7226ed3 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
@@ -12,7 +12,8 @@
<ul>
<li><a href="$expander.expandRef("common-definitions#sh-tokenization")">Bourne shell tokenization</a></li>
<li><a href="$expander.expandRef("common-definitions#label-expansion")">Label expansion</a></li>
- <li><a href="$expander.expandRef("common-definitions#common-attributes")">Common attributes</a></li>
+ <li><a href="$expander.expandRef("common-definitions#typical-attributes")">Typical attributes for most rules</a></li>
+ <li><a href="$expander.expandRef("common-definitions#common-attributes")">Common attributes for all rules</a></li>
<li><a href="$expander.expandRef("common-definitions#common-attributes-tests")">Common attributes for tests</a></li>
<li><a href="$expander.expandRef("common-definitions#common-attributes-binaries")">Common attributes for binaries</a></li>
<li><a href="$expander.expandRef("common-definitions#configurable-attributes")">Configurable attributes</a></li>
