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 552976c61d2323..a7438ad21eb07b 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 @@ private void processAttributeDocs(Iterable 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)); } } } 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 af957ff4c41cad..19a4ae71aab2b2 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 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"; 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 9bbdf6300f0f93..d930041f66e1c9 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 @@ 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", 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 d839ccadaf2534..e0f8608f7ffe67 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 @@ 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 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 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 generateAttributeMap( String commonType, ImmutableList filenames) { - ImmutableMap.Builder builder = - ImmutableMap.builder(); + ImmutableMap.Builder builder = ImmutableMap.builder(); for (String filename : filenames) { String name = Files.getNameWithoutExtension(filename); try { @@ -92,6 +101,9 @@ private static ImmutableMap generateAttribut return builder.build(); } + public static final ImmutableMap TYPICAL_ATTRIBUTES = + generateAttributeMap(DocgenConsts.TYPICAL_ATTRIBUTES, TYPICAL_ATTRIBUTES_DOCFILES); + public static final ImmutableMap 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 883b1411e92d3b..346cc339b3791d 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 @@ public void generateDocumentation(List 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", 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 01cb9c7e2b9ad4..aa17f6d5ab272c 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 @@

-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 run command or as a test. These arguments are passed before the ones that are specified on the bazel run or bazel test command line. @@ -15,12 +15,6 @@

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 bazel-bin/).

- -

-Most binary rules permit an args attribute, but where -this attribute is not allowed, this fact is documented under the -specific rule. -

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 80cb86bcbbfbf5..8885781f28c2b9 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 @@

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 bazel-bin/).

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 16fc1fefd53e92..3beb7eeee0026b 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 @@ -

List of labels; optional; nonconfigurable

+

List of labels; optional; + nonconfigurable

-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.

-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 ConstraintSemantics for details.

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 5be4ef2009bcf4..00000000000000 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html +++ /dev/null @@ -1,20 +0,0 @@ -

List of labels; optional

- -

-The list of files needed by this rule at runtime. -

- -

-Targets named in the data attribute will appear in -the *.runfiles 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 -data dependencies section for more -information about how to depend on and use data files. -

- -

-Almost all rules permit a data attribute, but where -this attribute is not allowed, this fact is documented under the -specific rule. -

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 abd667df563cd3..9ee89e4dcb10a5 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 @@

String; optional; nonconfigurable

-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 deprecation attribute is -depended upon by another rule. +depended upon by a target in another package.

@@ -25,10 +25,10 @@

-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.

-Once people have stopped using it, the package can be removed. +Once people have stopped using it, the target can be removed.

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 806e3dedc7a470..00000000000000 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html +++ /dev/null @@ -1,32 +0,0 @@ -

List of labels; optional

- -

-A list of dependencies of this rule. -

- -

-The precise semantics of what it means for this rule to depend on -another using deps 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 deps will -appear in the *.runfiles area of this rule, if it has -one. -

- -

-Most often, a deps 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 java_library rule may depend on C++ code in -a cc_library rule, by declaring the latter in -the deps attribute. See the definition -of dependencies for more -information. -

- -

-Almost all rules permit a deps attribute, but where -this attribute is not allowed, this fact is documented under the -specific rule. -

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 cd468dddd49b35..c54f7fc3c478de 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 @@

List of strings; optional; nonconfigurable

- 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 a920e6ad09e75d..c027e398139efe 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 @@ -

List of labels; optional; nonconfigurable

+

+List of labels; optional; +nonconfigurable +

A list of constraint_values 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 - toolchain resolution - for details. -

+to restrict the list of available execution platforms. For more details, see +the description of + toolchain resolution. +

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 ae6f0094cd30bc..9d3d73a1ca6734 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 @@ -

Dictionary of strings. Default is an empty dictionary.

+

Dictionary of strings; optional

A dictionary of strings that will be added to the exec_properties of a platform selected for this target. See exec_properties of the platform rule.

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 5ac9dd96c81acd..9358816f071742 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 @@ -

List of features. Default is the empty list.

+

List of feature strings; optional

A feature is string tag that can be enabled or disabled on a target. The meaning of a feature depends on the rule itself.

This features attribute is combined with the package level features 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 features attribute contains ["-a", "c"], the features enabled for the rule will be "b" and "c". 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 fb0ece459cbcbd..c3c2e5b6f18556 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 @@ -

List of labels; optional; nonconfigurable

+

List of labels; optional; + nonconfigurable

-The list of environments this rule can be built for, instead of +The list of environments this target can be built for, instead of default-supported environments.

-This is part of Bazel's soft-launched constraint system. See +This is part of Bazel's constraint system. See compatible_with for details.

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 f7a1fde401baab..4ffcbc9263154b 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 @@

- List of arbitrary text tags. Tags may be any valid string; default is - the empty list; nonconfigurable + List of strings; optional; nonconfigurable

Tags can be used on any rule. Tags on test and test_suite rules are useful for categorizing the tests. - Tags on non-test rules are used to control sandboxed execution of + Tags on non-test targets are used to control sandboxed execution of genrules and Starlark @@ -15,9 +14,9 @@

Bazel modifies the behavior of its sandboxing code if it finds the following - keywords in the tags attribute of any test rule or - genrule, or the keys of execution_requirements for - any Starlark action. + keywords in the tags attribute of any test or genrule + target, or the keys of execution_requirements for any Starlark + action.

    @@ -111,4 +110,4 @@
See Tag Conventions 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 c65186acb52806..5e698f9b07f5c3 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 @@

-List of labels; optional; default -is the empty list +List of labels; optional

A list of constraint_values 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 +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 (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 7c3871538a36db..736e49e0dccdb8 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 @@ -

Boolean; optional; default False except as noted; nonconfigurable

+

Boolean; optional; default False except for test and test suite targets; + nonconfigurable

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 be8933449a2ef7..645337d69fa63e 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 @@

List of labels; optional; nonconfigurable

- The set of targets whose Make variables the rule is allowed - to access. These rules are either rules that provide - the TemplateVariableInfo provider or special targets for toolchain types built into -Bazel. -These include: + The set of targets whose Make variables this target is + allowed to access. These targets are either instances of rules that provide + TemplateVariableInfo or special targets for toolchain types built into Bazel. These + include:

  • @bazel_tools//tools/cpp:current_cc_toolchain @@ -16,5 +15,6 @@ Note that this is distinct from the concept of toolchain resolution 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 cc_toolchain or java_toolchain a + target will use.

    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 749b02a60acbaa..ab95f54a526cef 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; nonconfigurable

    -The visibility attribute on a rule controls whether the rule can -be used by other packages. See the documentation for visibility. +The visibility attribute on a target controls whether the target +can be used in other packages. See the documentation for +visibility.

    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 7dab0d99d15570..c384583a3c5296 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 @@ "Make variable" substitution, and Bourne shell tokenization

    -

    Add these arguments to the --test_arg -when executed by bazel test.

    +

    Command line arguments that Bazel passes to the target when it is +executed with bazel test.

    -These arguments are passed before the --test_arg values +These arguments are passed before any --test_arg values specified on the bazel test command line.

    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 a2c8366696087d..22cceb477d854f 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 @@ -

    List of strings; optional

    +

    List of strings; optional

    Specifies additional environment variables to inherit from the external environment when the test is executed by bazel test. 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 3447010c80410e..6fc8590214e6e6 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 @@ -

    Boolean; optional; nonconfigurable

    +

    Boolean; optional; default False; nonconfigurable

    Marks test as flaky.

    -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.

    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 17d2683d93b920..a6e8c0ecc3c5a1 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 @@ -

    Boolean; optional; nonconfigurable

    +

    Boolean; default False; nonconfigurable

    Forces the test to be run locally, without sandboxing.

    -

    By default this attribute is set to 0 and the default testing strategy is -used. This is equivalent to providing "local" as a tag +

    Setting this to True is equivalent to providing "local" as a tag (tags=["local"]).

    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 2e7b4030aec9da..c9af3c9765bb04 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 @@ -

    Non-negative integer less than or equal to 50; -optional

    +

    Non-negative integer less than or equal to 50; optional

    Specifies the number of parallel shards to use to run the test.

    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 00000000000000..e86ab042aa03a1 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html @@ -0,0 +1,26 @@ + +

    List of labels; optional

    + +

    +Files needed by this rule at runtime. May list file or rule targets. Generally +allows any target. +

    + +

    +The default outputs and runfiles of targets in the data attribute +should appear in the *.runfiles 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 +srcs are executed. See the +data dependencies section for more +information about how to depend on and use data files. +

    + +

    +New rules should define a data attribute if they process +inputs which might use other inputs at runtime. Rules' implementation functions +must also populate the target's +runfiles from the outputs and runfiles of any data attribute, +as well as runfiles from any dependency attribute which provides either +source code or runtime dependencies. +

    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 00000000000000..6efe4e60ef1446 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html @@ -0,0 +1,31 @@ + +

    List of labels; optional

    + +

    +Dependencies for this target. Generally should only list rule targets. (Though +some rules permit files to be listed directly in deps, this +should be avoided when possible.) +

    + +

    +Language-specific rules generally limit the listed targets to those with +specific providers. +

    + +

    +The precise semantics of what it means for a target to depend on another using +deps are specific to the kind of rule, and the rule-specific +documentation goes into more detail. For rules which process source code, +deps generally specifies code dependencies used by the code in +srcs. +

    + +

    +Most often, a deps 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 java_library target may depend on C++ code +in a cc_library target, by listing the latter in the +deps attribute. See the definition of +dependencies for more information. +

    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 87% 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 d8392992fc0758..ca28662a6662b6 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 @@ +

    List of strings; optional; nonconfigurable

    - 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 00000000000000..9b7b1ade6bb2f5 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html @@ -0,0 +1,13 @@ +

    List of labels; + optional

    + +

    +Files processed or included by this rule. Generally lists files directly, but +may list rule targets (like filegroup or genrule) to +include their default outputs. +

    + +

    +Language-specific rules often require that the listed files have particular +file extensions. +

    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 08c69a02610616..717db6ddbde2e1 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 @@ title: Common Definitions

    Common definitions

    This section defines various terms and concepts that are common to -many functions or build rules below. +many functions or build rules.

    #if (!$singlePage) @@ -20,6 +20,7 @@ many functions or build rules below.