From b77cb789eac44168e8402e2b3d0331c21dce2c00 Mon Sep 17 00:00:00 2001 From: Googler Date: Wed, 12 Apr 2023 10:49:55 -0700 Subject: [PATCH] Docgen: Split the "global functions" page into multiple ones ====== - Primary motivation: https://github.com/bazelbuild/bazel/issues/16383 - Currently, the pages generated by docgen is a `PageTitle -> Page` map. It's then separated into multiple categories based on the `docCategory` value of the `@StarlarkBuiltin` annotation, with the exception of the "global functions" page, which is special-cased. - This has several issues: for one, the configuration fragment named "proto" has a conflict with the top-level module named "proto", since everything is in the same map (we work around this by naming the latter "ProtoModule", which is wrong and confusing). - For another, we can't easily split the "global functions" page into multiple ones, unless we special-case every one of them. - So we structure the returned pages into a `Category -> [Page]` map. The new category `GLOBAL_FUNCTION` contains a few pages, each of which contains global functions available in a certain environment (see https://github.com/bazelbuild/bazel/commit/d1c72d70f45c2362a87d22ebac9e5bb7f2b4ae0a). The other categories are largely unchanged. - We also change the URL format of these pages from `..../lib/$TITLE.html` to `..../lib/$CATEGORY/$TITLE.html`. - The bulk of this CL involves fixing up all links. - This also means that "proto" the configuration fragment and "proto" the top-level module can now both be named "proto". - This does break old links, but I can't find the energy to set up redirects for everything... - Miscellaneous changes: - The `starlark-nav.vm` page is removed; nobody uses it. - Renamed the category overview pages from `..../lib/starlark-$CATEGORY.html` to just `..../lib/$CATEGORY.html`, now that there's no pages directly under `..../lib`. - A bunch of small documentation fixes across the codebase as I went through them. Fixes https://github.com/bazelbuild/bazel/issues/16383 PiperOrigin-RevId: 523745069 Change-Id: Idfbb29f1f589bde58ac5a8b199a788245286256a --- site/en/concepts/platforms.md | 2 +- site/en/concepts/visibility.md | 2 +- site/en/configure/integrate-cpp.md | 18 +- site/en/docs/bazel-and-apple.md | 18 +- site/en/docs/bazel-and-java.md | 18 +- site/en/docs/cc-toolchain-config-reference.md | 4 +- site/en/docs/user-manual.md | 4 +- site/en/extending/aspects.md | 18 +- site/en/extending/concepts.md | 2 +- site/en/extending/config.md | 16 +- site/en/extending/depsets.md | 8 +- site/en/extending/exec-groups.md | 10 +- site/en/extending/macros.md | 10 +- site/en/extending/platforms.md | 2 +- site/en/extending/repo.md | 6 +- site/en/extending/rules.md | 112 +++---- site/en/extending/toolchains.md | 12 +- site/en/external/advanced.md | 6 +- site/en/external/extension.md | 14 +- site/en/external/module.md | 14 +- site/en/external/overview.md | 2 +- site/en/query/cquery.md | 2 +- site/en/remote/rules.md | 2 +- site/en/remote/workspace.md | 4 +- site/en/rules/language.md | 4 +- site/en/tutorials/ccp-toolchain-config.md | 4 +- .../devtools/build/docgen/ApiExporter.java | 96 +++--- .../devtools/build/docgen/DocgenConsts.java | 2 - .../StarlarkDocumentationCollector.java | 313 +++++++++--------- .../StarlarkDocumentationProcessor.java | 194 ++++------- .../devtools/build/docgen/SymbolFamilies.java | 11 +- .../build/docgen/annot/GlobalMethods.java | 26 +- .../docgen/starlark/StarlarkBuiltinDoc.java | 135 +------- .../build/docgen/starlark/StarlarkDoc.java | 32 +- .../docgen/starlark/StarlarkDocPage.java | 111 +++++++ .../docgen/starlark/StarlarkGlobalsDoc.java | 47 +++ .../docgen/templates/attributes/test/env.html | 2 +- .../build/docgen/templates/be/overview.vm | 2 +- .../docgen/templates/starlark-category.vm | 4 +- .../docgen/templates/starlark-library.vm | 12 +- .../build/docgen/templates/starlark-nav.vm | 5 - .../docgen/templates/starlark-overview.vm | 71 +--- .../build/docgen/templates/starlark-toc.vm | 20 +- .../java/com/google/devtools/build/lib/BUILD | 5 +- .../starlark/StarlarkRuleClassFunctions.java | 3 +- .../bazel/bzlmod/ModuleExtensionContext.java | 13 +- .../build/lib/collect/nestedset/Depset.java | 4 +- .../build/lib/packages/StarlarkLibrary.java | 19 +- .../build/lib/starlarkbuildapi/ActionApi.java | 57 ++-- .../BuildConfigurationApi.java | 2 +- .../starlarkbuildapi/CommandLineArgsApi.java | 120 +++---- .../lib/starlarkbuildapi/DefaultInfoApi.java | 30 +- .../starlarkbuildapi/DirectoryExpander.java | 4 +- .../build/lib/starlarkbuildapi/FileApi.java | 31 +- .../FragmentCollectionApi.java | 2 +- .../starlarkbuildapi/LateBoundDefaultApi.java | 4 +- .../lib/starlarkbuildapi/RunfilesApi.java | 10 +- .../StarlarkActionFactoryApi.java | 20 +- .../starlarkbuildapi/StarlarkAspectApi.java | 6 +- .../StarlarkAttrModuleApi.java | 103 +++--- .../StarlarkBuildApiGlobals.java | 14 +- .../StarlarkNativeModuleApi.java | 31 +- .../StarlarkRuleContextApi.java | 166 +++++----- .../StarlarkRuleFunctionsApi.java | 169 +++++----- .../lib/starlarkbuildapi/TemplateDictApi.java | 2 +- .../apple/ApplePlatformApi.java | 19 +- .../apple/ApplePlatformTypeApi.java | 9 +- .../apple/AppleToolchainApi.java | 2 +- .../config/ConfigGlobalLibraryApi.java | 5 +- .../starlarkbuildapi/core/ProviderApi.java | 4 +- .../core/TransitiveInfoCollectionApi.java | 27 +- .../cpp/CcCompilationContextApi.java | 2 +- .../cpp/CcLinkingOutputsApi.java | 6 +- .../cpp/CppConfigurationApi.java | 2 +- .../starlarkbuildapi/java/JavaCommonApi.java | 8 +- .../starlarkbuildapi/java/JavaInfoApi.java | 23 +- .../starlarkbuildapi/objc/AppleCommonApi.java | 43 +-- .../platform/PlatformCommonApi.java | 13 +- .../proto/ProtoCommonApi.java | 8 +- .../repository/RepositoryModuleApi.java | 18 +- .../test/CoverageCommonApi.java | 8 +- .../test/CoverageConfigurationApi.java | 2 +- .../test/InstrumentedFilesInfoApi.java | 23 +- .../test/TestingModuleApi.java | 28 +- .../FakeStarlarkRuleFunctionsApi.java | 5 +- .../java/net/starlark/java/eval/Dict.java | 23 +- .../net/starlark/java/eval/MethodLibrary.java | 2 +- .../net/starlark/java/eval/StringModule.java | 4 +- .../docgen/StarlarkDocumentationTest.java | 228 +++++++------ 89 files changed, 1322 insertions(+), 1402 deletions(-) create mode 100644 src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java create mode 100644 src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java delete mode 100644 src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm diff --git a/site/en/concepts/platforms.md b/site/en/concepts/platforms.md index 6db86089a2e4c8..57fc15027da1a3 100644 --- a/site/en/concepts/platforms.md +++ b/site/en/concepts/platforms.md @@ -418,7 +418,7 @@ contact [bazel-dev]{: .external}. [Platforms examples]: https://github.com/hlopko/bazel_platforms_examples [platform mappings design]: https://docs.google.com/document/d/1Vg_tPgiZbSrvXcJ403vZVAGlsWhH9BUDrAxMOYnO0Ls/edit [platform Rule]: /reference/be/platform#platform -[register_toolchains Function]: /rules/lib/globals#register_toolchains +[register_toolchains Function]: /rules/lib/globals/workspace#register_toolchains [Rust rules]: https://github.com/bazelbuild/rules_rust [select()]: /docs/configurable-attributes [select() Platforms]: /docs/configurable-attributes#platforms diff --git a/site/en/concepts/visibility.md b/site/en/concepts/visibility.md index e13f5ea92bf18b..dab44fd9460712 100644 --- a/site/en/concepts/visibility.md +++ b/site/en/concepts/visibility.md @@ -275,7 +275,7 @@ Load visibility is available as of Bazel 6.0. ### Declaring load visibility {:#declaring-load-visibility} To set the load visibility of a `.bzl` file, call the -[`visibility()`](/rules/lib/globals#visibility) function from within the file. +[`visibility()`](/rules/lib/globals/bzl#visibility) function from within the file. The argument to `visibility()` is a list of package specifications, just like the [`packages`](/reference/be/functions#package_group.packages) attribute of `package_group`. However, `visibility()` does not accept negative package diff --git a/site/en/configure/integrate-cpp.md b/site/en/configure/integrate-cpp.md index 7f1c84e961ef0d..8a01fd3eb81874 100644 --- a/site/en/configure/integrate-cpp.md +++ b/site/en/configure/integrate-cpp.md @@ -17,14 +17,14 @@ should use the helper function available at [@bazel_tools//tools/cpp:toolchain_utils.bzl](https://source.bazel.build/bazel/+/main:tools/cpp/toolchain_utils.bzl;l=23), which works both when toolchains are disabled and enabled. To depend on a C++ toolchain in your rule, add a -[`Label`](/rules/lib/attr#label) +[`Label`](/rules/lib/toplevel/attr#label) attribute named `_cc_toolchain` and point it to `@bazel_tools//tools/cpp:current_cc_toolchain` (an instance of `cc_toolchain_alias` rule, that points to the currently selected C++ toolchain). Then, in the rule implementation, use [`find_cpp_toolchain(ctx)`](https://source.bazel.build/bazel/+/main:tools/cpp/toolchain_utils.bzl;l=23) to get the -[`CcToolchainInfo`](/rules/lib/CcToolchainInfo). +[`CcToolchainInfo`](/rules/lib/providers/CcToolchainInfo). A complete working example can be found [in the rules_cc examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/write_cc_toolchain_cpu/write_cc_toolchain_cpu.bzl){: .external}. @@ -42,14 +42,14 @@ you need the following: * `features` and `action_configs` - these come from the `CcToolchainConfigInfo` and encapsulated in `CcToolchainInfo` -* `FeatureConfiguration` - returned by [cc_common.configure_features](/rules/lib/cc_common#configure_features) +* `FeatureConfiguration` - returned by [cc_common.configure_features](/rules/lib/toplevel/cc_common#configure_features) * cc toolchain config variables - returned by - [cc_common.create_compile_variables](/rules/lib/cc_common#create_compile_variables) + [cc_common.create_compile_variables](/rules/lib/toplevel/cc_common#create_compile_variables) or - [cc_common.create_link_variables](/rules/lib/cc_common#create_link_variables). + [cc_common.create_link_variables](/rules/lib/toplevel/cc_common#create_link_variables). There still are tool-specific getters, such as -[compiler_executable](/rules/lib/CcToolchainInfo#compiler_executable). +[compiler_executable](/rules/lib/providers/CcToolchainInfo#compiler_executable). Prefer `get_tool_for_action` over these, as tool-specific getters will eventually be removed. @@ -59,10 +59,10 @@ A complete working example can be found ## Implementing Starlark rules that depend on C++ rules and/or that C++ rules can depend on {:#implement-starlark-rules} Most C++ rules provide -[`CcInfo`](/rules/lib/CcInfo), -a provider containing [`CompilationContext`](/rules/lib/CompilationContext) +[`CcInfo`](/rules/lib/providers/CcInfo), +a provider containing [`CompilationContext`](/rules/lib/builtins/CompilationContext) and -[`LinkingContext`](/rules/lib/LinkingContext). +[`LinkingContext`](/rules/lib/builtins/LinkingContext). Through these it is possible to access information such as all transitive headers or libraries to link. From `CcInfo` and from the `CcToolchainInfo` custom Starlark rules should be able to get all the information they need. diff --git a/site/en/docs/bazel-and-apple.md b/site/en/docs/bazel-and-apple.md index 3c750fdb495a63..443c6c92e4f6bf 100644 --- a/site/en/docs/bazel-and-apple.md +++ b/site/en/docs/bazel-and-apple.md @@ -36,20 +36,20 @@ when building your macOS and iOS projects: * Modules: - * [`apple_bitcode_mode`](/rules/lib/apple_bitcode_mode) - * [`apple_common`](/rules/lib/apple_common) - * [`apple_platform`](/rules/lib/apple_platform) - * [`apple_platform_type`](/rules/lib/apple_platform_type) - * [`apple_toolchain`](/rules/lib/apple_toolchain) - * [`XcodeVersionConfig`](/rules/lib/XcodeVersionConfig) + * [`apple_bitcode_mode`](/rules/lib/builtins/apple_bitcode_mode) + * [`apple_common`](/rules/lib/toplevel/apple_common) + * [`apple_platform`](/rules/lib/builtins/apple_platform) + * [`apple_platform_type`](/rules/lib/builtins/apple_platform_type) + * [`apple_toolchain`](/rules/lib/builtins/apple_toolchain) * Configuration fragments: - * [`apple`](/rules/lib/apple) + * [`apple`](/rules/lib/fragments/apple) * Providers: - * [`ObjcProvider`](/rules/lib/ObjcProvider) + * [`ObjcProvider`](/rules/lib/providers/ObjcProvider) + * [`XcodeVersionConfig`](/rules/lib/providers/XcodeVersionConfig) ## Xcode selection {:#xcode-selection} @@ -61,7 +61,7 @@ the set of available Xcode versions and sets a default version if represented in the `--xcode_config` target. If you do not pass `--xcode_config`, Bazel will use the autogenerated -[`XcodeVersionConfig`](/rules/lib/XcodeVersionConfig) that represents the +[`XcodeVersionConfig`](/rules/lib/providers/XcodeVersionConfig) that represents the Xcode versions available on your host machine. The default version is the newest available Xcode version. This is appropriate for local execution. diff --git a/site/en/docs/bazel-and-java.md b/site/en/docs/bazel-and-java.md index 9a9132d8456b5b..ea8a11b88e139f 100644 --- a/site/en/docs/bazel-and-java.md +++ b/site/en/docs/bazel-and-java.md @@ -131,17 +131,17 @@ The following modules, configuration fragments, and providers will help you [extend Bazel's capabilities](/extending/concepts) when building your Java projects: -* Main Java provider: [`java_common`](/rules/lib/java_common) -* Main Java module: [`JavaInfo`](/rules/lib/JavaInfo) -* Configuration fragment: [`java`](/rules/lib/java) +* Main Java module: [`java_common`](/rules/lib/toplevel/java_common) +* Main Java provider: [`JavaInfo`](/rules/lib/providers/JavaInfo) +* Configuration fragment: [`java`](/rules/lib/fragments/java) * Other modules: - * [`java_annotation_processing`](/rules/lib/java_annotation_processing) - * [`java_compilation_info`](/rules/lib/java_compilation_info) - * [`java_output`](/rules/lib/java_output) - * [`java_output_jars`](/rules/lib/java_output_jars) - * [`JavaRuntimeInfo`](/rules/lib/JavaRuntimeInfo) - * [`JavaToolchainInfo`](/rules/lib/JavaToolchainInfo) + * [`java_annotation_processing`](/rules/lib/builtins/java_annotation_processing) + * [`java_compilation_info`](/rules/lib/providers/java_compilation_info) + * [`java_output`](/rules/lib/builtins/java_output) + * [`java_output_jars`](/rules/lib/providers/java_output_jars) + * [`JavaRuntimeInfo`](/rules/lib/providers/JavaRuntimeInfo) + * [`JavaToolchainInfo`](/rules/lib/providers/JavaToolchainInfo) ## Configuring the Java toolchains {:#config-java-toolchains} diff --git a/site/en/docs/cc-toolchain-config-reference.md b/site/en/docs/cc-toolchain-config-reference.md index be0be1022b6778..c7e38542baf208 100644 --- a/site/en/docs/cc-toolchain-config-reference.md +++ b/site/en/docs/cc-toolchain-config-reference.md @@ -28,14 +28,14 @@ Bazel needs to know the following: If the compiler has support for multiple architectures, Bazel needs to configure them separately. -[`CcToolchainConfigInfo`](/rules/lib/CcToolchainConfigInfo) is a provider that provides the necessary level of +[`CcToolchainConfigInfo`](/rules/lib/providers/CcToolchainConfigInfo) is a provider that provides the necessary level of granularity for configuring the behavior of Bazel's C++ rules. By default, Bazel automatically configures `CcToolchainConfigInfo` for your build, but you have the option to configure it manually. For that, you need a Starlark rule that provides the `CcToolchainConfigInfo` and you need to point the [`toolchain_config`](/reference/be/c-cpp#cc_toolchain.toolchain_config) attribute of the `cc_toolchain` to your rule. You can create the `CcToolchainConfigInfo` by calling -[`cc_common.create_cc_toolchain_config_info()`](/rules/lib/cc_common#create_cc_toolchain_config_info). +[`cc_common.create_cc_toolchain_config_info()`](/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info). You can find Starlark constructors for all structs you'll need in the process in [`@rules_cc//cc:cc_toolchain_config_lib.bzl`](https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl){: .external}. diff --git a/site/en/docs/user-manual.md b/site/en/docs/user-manual.md index 75aa2d974f8d99..b593b82aec7bc7 100644 --- a/site/en/docs/user-manual.md +++ b/site/en/docs/user-manual.md @@ -1325,7 +1325,7 @@ The label of a platform rule that describes the host system. The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These platforms will be considered before those declared in the WORKSPACE file by -[register_execution_platforms()](/rules/lib/globals#register_execution_platforms). +[register_execution_platforms()](/rules/lib/globals/workspace#register_execution_platforms). This option accepts a comma-separated list of platforms in order of priority. If the flag is passed multiple times, the most recent overrides. @@ -1334,7 +1334,7 @@ If the flag is passed multiple times, the most recent overrides. The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in the WORKSPACE file by -[register_toolchains()](/rules/lib/globals#register_toolchains). +[register_toolchains()](/rules/lib/globals/workspace#register_toolchains). #### `--toolchain_resolution_debug={{ "" }}regex{{ "" }}` {:#toolchain-resolution-debug} diff --git a/site/en/extending/aspects.md b/site/en/extending/aspects.md index ecd89d2e365dd6..e8257575071632 100644 --- a/site/en/extending/aspects.md +++ b/site/en/extending/aspects.md @@ -6,7 +6,7 @@ Book: /_book.yaml {% include "_buttons.html" %} This page explains the basics and benefits of using -[aspects](/rules/lib/globals#aspect) and provides simple and advanced +[aspects](/rules/lib/globals/bzl#aspect) and provides simple and advanced examples. Aspects allow augmenting build dependency graphs with additional information @@ -111,7 +111,7 @@ print_aspect = aspect( ) ``` Aspect definitions are similar to rule definitions, and defined using -the [`aspect`](/rules/lib/globals#aspect) function. +the [`aspect`](/rules/lib/globals/bzl#aspect) function. Just like a rule, an aspect has an implementation function which in this case is ``_print_aspect_impl``. @@ -141,12 +141,12 @@ Aspect implementation functions are similar to the rule implementation functions. They return [providers](/extending/rules#providers), can generate [actions](/extending/rules#actions), and take two arguments: -* `target`: the [target](/rules/lib/Target) the aspect is being applied to. -* `ctx`: [`ctx`](/rules/lib/ctx) object that can be used to access attributes +* `target`: the [target](/rules/lib/builtins/Target) the aspect is being applied to. +* `ctx`: [`ctx`](/rules/lib/builtins/ctx) object that can be used to access attributes and generate outputs and actions. The implementation function can access the attributes of the target rule via -[`ctx.rule.attr`](/rules/lib/ctx#rule). It can examine providers that are +[`ctx.rule.attr`](/rules/lib/builtins/ctx#rule). It can examine providers that are provided by the target to which it is applied (via the `target` argument). Aspects are required to return a list of providers. In this example, the aspect @@ -329,12 +329,12 @@ implementation of aspect A. The providers that a rule implementation propagates are created and frozen before aspects are applied and cannot be modified from an aspect. It is an error if a target and an aspect that is applied to it each provide a provider with the same type, with the exceptions of -[`OutputGroupInfo`](/rules/lib/OutputGroupInfo) +[`OutputGroupInfo`](/rules/lib/providers/OutputGroupInfo) (which is merged, so long as the rule and aspect specify different output groups) and -[`InstrumentedFilesInfo`](/rules/lib/InstrumentedFilesInfo) +[`InstrumentedFilesInfo`](/rules/lib/providers/InstrumentedFilesInfo) (which is taken from the aspect). This means that aspect implementations may -never return [`DefaultInfo`](/rules/lib/DefaultInfo). +never return [`DefaultInfo`](/rules/lib/providers/DefaultInfo). The parameters and private attributes are passed in the attributes of the ``ctx``. This example references the ``extension`` parameter and determines @@ -401,4 +401,4 @@ itself, and all of the targets accessible recursively via ``deps``. ## References -* [`aspect` API reference](/rules/lib/globals#aspect) +* [`aspect` API reference](/rules/lib/globals/bzl#aspect) diff --git a/site/en/extending/concepts.md b/site/en/extending/concepts.md index e71d365b133186..e03e7dbcfa079b 100644 --- a/site/en/extending/concepts.md +++ b/site/en/extending/concepts.md @@ -83,7 +83,7 @@ they will not be executed. The two links below will be very useful when writing your own extensions. Keep them within reach: -* The [API reference](/rules/lib/starlark-overview) +* The [API reference](/rules/lib) * [Examples](https://github.com/bazelbuild/examples/tree/master/rules) diff --git a/site/en/extending/config.md b/site/en/extending/config.md index 1288c6c84d6a31..1b4dbb312b2c9e 100644 --- a/site/en/extending/config.md +++ b/site/en/extending/config.md @@ -14,7 +14,7 @@ This makes it possible to: * define custom flags for your project, obsoleting the need for [`--define`](/docs/configurable-attributes#custom-keys) * write - [transitions](/rules/lib/transition#transition) to configure deps in + [transitions](/rules/lib/builtins/transition#transition) to configure deps in different configurations than their parents (such as `--compilation_mode=opt` or `--cpu=arm`) * bake better defaults into rules (such as automatically build `//my:android_app` @@ -50,7 +50,7 @@ set via [user-defined transitions](#user-defined-transitions). Build settings are rules like any other rule and are differentiated using the Starlark `rule()` function's `build_setting` -[attribute](/rules/lib/globals#rule.build_setting). +[attribute](/rules/lib/globals/bzl#rule.build_setting). ```python # example/buildsettings/build_settings.bzl @@ -63,13 +63,13 @@ string_flag = rule( The `build_setting` attribute takes a function that designates the type of the build setting. The type is limited to a set of basic Starlark types like `bool` and `string`. See the `config` module -[documentation](/rules/lib/config) for details. More complicated typing can be +[documentation](/rules/lib/toplevel/config) for details. More complicated typing can be done in the rule's implementation function. More on this below. The `config` module's functions takes an optional boolean parameter, `flag`, which is set to false by default. if `flag` is set to true, the build setting can be set on the command line by users as well as internally by rule writers -via default values and [transitions](/rules/lib/transition#transition). +via default values and [transitions](/rules/lib/builtins/transition#transition). Not all settings should be settable by users. For example, if you as a rule writer have some debug mode that you'd like to turn on inside test rules, you don't want to give users the ability to indiscriminately turn on that @@ -80,7 +80,7 @@ feature inside other non-test rules. Like all rules, build setting rules have [implementation functions](/extending/rules#implementation-function). The basic Starlark-type value of the build settings can be accessed via the `ctx.build_setting_value` method. This method is only available to -[`ctx`](/rules/lib/ctx) objects of build setting rules. These implementation +[`ctx`](/rules/lib/builtins/ctx) objects of build setting rules. These implementation methods can directly forward the build settings value or do additional work on it, like type checking or more complex struct creation. Here's how you would implement an `enum`-typed build setting: @@ -328,7 +328,7 @@ can't customely defined. Label-typed settings will eventually replace the functionality of late-bound defaults. Late-bound default attributes are Label-typed attributes whose final values can be affected by configuration. In Starlark, this will replace -the [`configuration_field`](/rules/lib/globals#configuration_field) +the [`configuration_field`](/rules/lib/globals/bzl#configuration_field) API. ```python @@ -388,7 +388,7 @@ config_setting( ## User-defined transitions {:#user-defined-transitions} A configuration -[transition](/rules/lib/transition#transition) +[transition](/rules/lib/builtins/transition#transition) maps the transformation from one configured target to another within the build graph. @@ -423,7 +423,7 @@ with special restrictions. In Starlark, transitions are defined much like rules, with a defining `transition()` -[function](/rules/lib/transition#transition) +[function](/rules/lib/builtins/transition#transition) and an implementation function. ```python diff --git a/site/en/extending/depsets.md b/site/en/extending/depsets.md index d69f1c3724127c..07f00f48b93271 100644 --- a/site/en/extending/depsets.md +++ b/site/en/extending/depsets.md @@ -5,7 +5,7 @@ Book: /_book.yaml {% include "_buttons.html" %} -[Depsets](/rules/lib/depset) are a specialized data structure for efficiently +[Depsets](/rules/lib/builtins/depset) are a specialized data structure for efficiently collecting data across a target’s transitive dependencies. They are an essential element of rule processing. @@ -35,7 +35,7 @@ previous without having to read or copy them. Each node in the DAG holds a list of direct elements and a list of child nodes. The contents of the depset are the transitive elements, such as the direct elements of all the nodes. A new depset can be created using the -[depset](/rules/lib/globals#depset) constructor: it accepts a list of direct +[depset](/rules/lib/globals/bzl#depset) constructor: it accepts a list of direct elements and another list of child nodes. ```python @@ -47,7 +47,7 @@ print(t) # depset(["d", "e", "a", "b", "c"]) ``` To retrieve the contents of a depset, use the -[to_list()](/rules/lib/depset#to_list) method. It returns a list of all transitive +[to_list()](/rules/lib/builtins/depset#to_list) method. It returns a list of all transitive elements, not including duplicates. There is no way to directly inspect the precise structure of the DAG, although this structure does affect the order in which the elements are returned. @@ -343,5 +343,5 @@ For more information about using depsets efficiently, see the [performance](/rul ## API Reference -Please see [here](/rules/lib/depset) for more details. +Please see [here](/rules/lib/builtins/depset) for more details. diff --git a/site/en/extending/exec-groups.md b/site/en/extending/exec-groups.md index 9abdf1dfd208f1..80492e1fa51057 100644 --- a/site/en/extending/exec-groups.md +++ b/site/en/extending/exec-groups.md @@ -25,7 +25,7 @@ like linking in C++ builds without over-allocating to less demanding tasks. ## Defining execution groups {:#defining-exec-groups} During rule definition, rule authors can -[declare](/rules/lib/globals#exec_group) +[declare](/rules/lib/globals/bzl#exec_group) a set of execution groups. On each execution group, the rule author can specify everything needed to select an execution platform for that execution group, namely any constraints via `exec_compatible_with` and toolchain types via @@ -52,9 +52,9 @@ my_rule = rule( In the code snippet above, you can see that tool dependencies can also specify transition for an exec group using the -[`cfg`](/rules/lib/attr#label) +[`cfg`](/rules/lib/toplevel/attr#label) attribute param and the -[`config`](/rules/lib/config) +[`config`](/rules/lib/toplevel/config) module. The module exposes an `exec` function which takes a single string parameter which is the name of the exec group for which the dependency should be built. @@ -109,8 +109,8 @@ of: In the rule implementation, you can declare that actions should be run on the execution platform of an execution group. You can do this by using the `exec_group` param of action generating methods, specifically [`ctx.actions.run`] -(/rules/lib/actions#run) and -[`ctx.actions.run_shell`](/rules/lib/actions#run_shell). +(/rules/lib/builtins/actions#run) and +[`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell). ```python # foo.bzl diff --git a/site/en/extending/macros.md b/site/en/extending/macros.md index 356383e1b9a871..a6ba77c18360f0 100644 --- a/site/en/extending/macros.md +++ b/site/en/extending/macros.md @@ -125,7 +125,7 @@ genrule( ## Instantiating native rules {:#instantiating-native-rules} Native rules (rules that don't need a `load()` statement) can be -instantiated from the [native](/rules/lib/native) module: +instantiated from the [native](/rules/lib/toplevel/native) module: ```python def my_macro(name, visibility=None): @@ -137,7 +137,7 @@ def my_macro(name, visibility=None): ``` If you need to know the package name (for example, which `BUILD` file is calling the -macro), use the function [native.package_name()](/rules/lib/native#package_name). +macro), use the function [native.package_name()](/rules/lib/toplevel/native#package_name). Note that `native` can only be used in `.bzl` files, and not in `WORKSPACE` or `BUILD` files. @@ -151,7 +151,7 @@ for macros that are meant to be used in other repositories, such as because they are part of a published Starlark ruleset. To get the same behavior as for Starlark rules, wrap the label strings with the -[`Label`](/rules/lib/Label#Label) constructor: +[`Label`](/rules/lib/builtins/Label#Label) constructor: ```python # @my_ruleset//rules:defs.bzl @@ -191,7 +191,7 @@ def my_cc_wrapper(name, deps = [], **kwargs): the rule `foo` is created (due to a name conflict), which will show you the full stack trace. -* You can also use [print](/rules/lib/globals#print) for debugging. It displays +* You can also use [print](/rules/lib/globals/all#print) for debugging. It displays the message as a `DEBUG` log line during the loading phase. Except in rare cases, either remove `print` calls, or make them conditional under a `debugging` parameter that defaults to `False` before submitting the code to @@ -199,7 +199,7 @@ def my_cc_wrapper(name, deps = [], **kwargs): ## Errors {:#errors} -If you want to throw an error, use the [fail](/rules/lib/globals#fail) function. +If you want to throw an error, use the [fail](/rules/lib/globals/all#fail) function. Explain clearly to the user what went wrong and how to fix their `BUILD` file. It is not possible to catch an error. diff --git a/site/en/extending/platforms.md b/site/en/extending/platforms.md index fa8e4e6ac6a8a1..3fa20dc7eca38c 100644 --- a/site/en/extending/platforms.md +++ b/site/en/extending/platforms.md @@ -233,7 +233,7 @@ cc_library( ### Detecting incompatible targets using `bazel cquery` {:#cquery-incompatible-target-detection} You can use the -[`IncompatiblePlatformProvider`](/rules/lib/IncompatiblePlatformProvider) +[`IncompatiblePlatformProvider`](/rules/lib/providers/IncompatiblePlatformProvider) in `bazel cquery`'s [Starlark output format](/query/cquery#output-format-definition) to distinguish incompatible targets from compatible ones. diff --git a/site/en/extending/repo.md b/site/en/extending/repo.md index 526ad86a6e0fd8..d841f44c2e13d7 100644 --- a/site/en/extending/repo.md +++ b/site/en/extending/repo.md @@ -18,7 +18,7 @@ specific to the host Bazel is running on. ## Repository rule creation In a `.bzl` file, use the -[repository_rule](/rules/lib/globals#repository_rule) function to create a new +[repository_rule](/rules/lib/globals/bzl#repository_rule) function to create a new repository rule and store it in a global variable. A custom repository rule can be used just like a native repository rule. It @@ -71,7 +71,7 @@ specified. The input parameter `repository_ctx` can be used to access attribute values, and non-hermetic functions (finding a binary, executing a binary, creating a file in the repository or downloading a file -from the Internet). See [the library](/rules/lib/repository_ctx) for more +from the Internet). See [the library](/rules/lib/builtins/repository_ctx) for more context. Example: ```python @@ -102,7 +102,7 @@ following things changes: `WORKSPACE` file. * The Starlark code comprising the implementation of the repository. * The value of any environment variable declared with the `environ` - attribute of the [`repository_rule`](/rules/lib/globals#repository_rule). + attribute of the [`repository_rule`](/rules/lib/globals/bzl#repository_rule). The values of these environment variables can be hard-wired on the command line with the [`--action_env`](/reference/command-line-reference#flag--action_env) diff --git a/site/en/extending/rules.md b/site/en/extending/rules.md index 440ad0c9d4d02c..e4f5ece6c00b5c 100644 --- a/site/en/extending/rules.md +++ b/site/en/extending/rules.md @@ -50,7 +50,7 @@ needed. ## Rule creation -In a `.bzl` file, use the [rule](/rules/lib/globals#rule) function to define a new +In a `.bzl` file, use the [rule](/rules/lib/globals/bzl#rule) function to define a new rule, and store the result in a global variable. The call to `rule` specifies [attributes](#attributes) and an [implementation function](#implementation_function): @@ -103,7 +103,7 @@ target's [implementation](#implementation_function), or they can refer to other targets, creating a graph of dependencies. Rule-specific attributes, such as `srcs` or `deps`, are defined by passing a map -from attribute names to schemas (created using the [`attr`](/rules/lib/attr) +from attribute names to schemas (created using the [`attr`](/rules/lib/toplevel/attr) module) to the `attrs` parameter of `rule`. [Common attributes](/reference/be/common-definitions#common-attributes), such as `name` and `visibility`, are implicitly added to all rules. Additional @@ -144,12 +144,12 @@ example_library = rule( These are examples of *dependency attributes*. Any attribute that specifies an input label (those defined with -[`attr.label_list`](/rules/lib/attr#label_list), -[`attr.label`](/rules/lib/attr#label), or -[`attr.label_keyed_string_dict`](/rules/lib/attr#label_keyed_string_dict)) +[`attr.label_list`](/rules/lib/toplevel/attr#label_list), +[`attr.label`](/rules/lib/toplevel/attr#label), or +[`attr.label_keyed_string_dict`](/rules/lib/toplevel/attr#label_keyed_string_dict)) specifies dependencies of a certain type between a target and the targets whose labels (or the corresponding -[`Label`](/rules/lib/Label) objects) are listed in that attribute when the target +[`Label`](/rules/lib/builtins/Label) objects) are listed in that attribute when the target is defined. The repository, and possibly the path, for these labels is resolved relative to the defined target. @@ -220,8 +220,8 @@ rule should obtain that tool from a [toolchain](/extending/toolchains). ### Output attributes -*Output attributes*, such as [`attr.output`](/rules/lib/attr#output) and -[`attr.output_list`](/rules/lib/attr#output_list), declare an output file that the +*Output attributes*, such as [`attr.output`](/rules/lib/toplevel/attr#output) and +[`attr.output_list`](/rules/lib/toplevel/attr#output_list), declare an output file that the target generates. These differ from dependency attributes in two ways: * They define output file targets instead of referring to targets defined @@ -250,16 +250,16 @@ underscore). Conventionally, they are named the same as their rule, but suffixed with `_impl`. Implementation functions take exactly one parameter: a -[rule context](/rules/lib/ctx), conventionally named `ctx`. They return a list of +[rule context](/rules/lib/builtins/ctx), conventionally named `ctx`. They return a list of [providers](#providers). ### Targets -Dependencies are represented at analysis time as [`Target`](/rules/lib/Target) +Dependencies are represented at analysis time as [`Target`](/rules/lib/builtins/Target) objects. These objects contain the [providers](#providers) generated when the target's implementation function was executed. -[`ctx.attr`](/rules/lib/ctx#attr) has fields corresponding to the names of each +[`ctx.attr`](/rules/lib/builtins/ctx#attr) has fields corresponding to the names of each dependency attribute, containing `Target` objects representing each direct dependency via that attribute. For `label_list` attributes, this is a list of `Targets`. For `label` attributes, this is a single `Target` or `None`. @@ -272,7 +272,7 @@ return [ExampleInfo(headers = depset(...))] Those can be accessed using index notation (`[]`), with the type of provider as a key. These can be [custom providers](#custom_providers) defined in Starlark or -[providers for native rules](/rules/lib/starlark-provider) available as Starlark +[providers for native rules](/rules/lib/providers) available as Starlark global variables. For example, if a rule takes header files via a `hdrs` attribute and provides @@ -285,7 +285,7 @@ def _example_library_impl(ctx): transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs] ``` -For the legacy style in which a [`struct`](/rules/lib/struct) is returned from a +For the legacy style in which a [`struct`](/rules/lib/builtins/struct) is returned from a target's implementation function instead of a list of provider objects: ```python @@ -303,10 +303,10 @@ This style is strongly discouraged and rules should be ### Files -Files are represented by [`File`](/rules/lib/File) objects. Since Bazel does not +Files are represented by [`File`](/rules/lib/builtins/File) objects. Since Bazel does not perform file I/O during the analysis phase, these objects cannot be used to directly read or write file content. Rather, they are passed to action-emitting -functions (see [`ctx.actions`](/rules/lib/actions)) to construct pieces of the +functions (see [`ctx.actions`](/rules/lib/builtins/actions)) to construct pieces of the action graph. A `File` can either be a source file or a generated file. Each generated file @@ -314,7 +314,7 @@ must be an output of exactly one action. Source files cannot be the output of any action. For each dependency attribute, the corresponding field of -[`ctx.files`](/rules/lib/ctx#files) contains a list of the default outputs of all +[`ctx.files`](/rules/lib/builtins/ctx#files) contains a list of the default outputs of all dependencies via that attribute: ```python @@ -325,9 +325,9 @@ def _example_library_impl(ctx): ... ``` -[`ctx.file`](/rules/lib/ctx#file) contains a single `File` or `None` for +[`ctx.file`](/rules/lib/builtins/ctx#file) contains a single `File` or `None` for dependency attributes whose specs set `allow_single_file=True`. -[`ctx.executable`](/rules/lib/ctx#executable) behaves the same as `ctx.file`, but only +[`ctx.executable`](/rules/lib/builtins/ctx#executable) behaves the same as `ctx.file`, but only contains fields for dependency attributes whose specs set `executable=True`. ### Declaring outputs @@ -335,10 +335,10 @@ contains fields for dependency attributes whose specs set `executable=True`. During the analysis phase, a rule's implementation function can create outputs. Since all labels have to be known during the loading phase, these additional outputs have no labels. `File` objects for outputs can be created using -[`ctx.actions.declare_file`](/rules/lib/actions#declare_file) and -[`ctx.actions.declare_directory`](/rules/lib/actions#declare_directory). Often, +[`ctx.actions.declare_file`](/rules/lib/builtins/actions#declare_file) and +[`ctx.actions.declare_directory`](/rules/lib/builtins/actions#declare_directory). Often, the names of outputs are based on the target's name, -[`ctx.label.name`](/rules/lib/ctx#label): +[`ctx.label.name`](/rules/lib/builtins/ctx#label): ```python def _example_library_impl(ctx): @@ -349,7 +349,7 @@ def _example_library_impl(ctx): For *predeclared outputs*, like those created for [output attributes](#output_attributes), `File` objects instead can be retrieved -from the corresponding fields of [`ctx.outputs`](/rules/lib/ctx#outputs). +from the corresponding fields of [`ctx.outputs`](/rules/lib/builtins/ctx#outputs). ### Actions @@ -360,16 +360,16 @@ because an action can depend on the output of another action. For example, in C, the linker must be called after the compiler. General-purpose functions that create actions are defined in -[`ctx.actions`](/rules/lib/actions): +[`ctx.actions`](/rules/lib/builtins/actions): -* [`ctx.actions.run`](/rules/lib/actions#run), to run an executable. -* [`ctx.actions.run_shell`](/rules/lib/actions#run_shell), to run a shell +* [`ctx.actions.run`](/rules/lib/builtins/actions#run), to run an executable. +* [`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell), to run a shell command. -* [`ctx.actions.write`](/rules/lib/actions#write), to write a string to a file. -* [`ctx.actions.expand_template`](/rules/lib/actions#expand_template), to +* [`ctx.actions.write`](/rules/lib/builtins/actions#write), to write a string to a file. +* [`ctx.actions.expand_template`](/rules/lib/builtins/actions#expand_template), to generate a file from a template. -[`ctx.actions.args`](/rules/lib/actions#args) can be used to efficiently +[`ctx.actions.args`](/rules/lib/builtins/actions#args) can be used to efficiently accumulate the arguments for actions. It avoids flattening depsets until execution time: @@ -434,13 +434,13 @@ about. Since a rule's implementation function can only read providers from the instantiated target's immediate dependencies, rules need to forward any information from a target's dependencies that needs to be known by a target's -consumers, generally by accumulating that into a [`depset`](/rules/lib/depset). +consumers, generally by accumulating that into a [`depset`](/rules/lib/builtins/depset). A target's providers are specified by a list of `Provider` objects returned by the implementation function. Old implementation functions can also be written in a legacy style where the -implementation function returns a [`struct`](/rules/lib/struct) instead of list of +implementation function returns a [`struct`](/rules/lib/builtins/struct) instead of list of provider objects. This style is strongly discouraged and rules should be [migrated away from it](#migrating_from_legacy_providers). @@ -452,7 +452,7 @@ the target is requested for build at the command line. For example, a will be built by the command `bazel build //pkg:foo`. Default outputs are specified by the `files` parameter of -[`DefaultInfo`](/rules/lib/DefaultInfo): +[`DefaultInfo`](/rules/lib/providers/DefaultInfo): ```python def _example_library_impl(ctx): @@ -483,8 +483,8 @@ a directory tree containing symlinks pointing to the runfiles. This stages the environment for the binary so it can access the runfiles during runtime. Runfiles can be added manually during rule creation. -[`runfiles`](/rules/lib/runfiles) objects can be created by the `runfiles` method -on the rule context, [`ctx.runfiles`](/rules/lib/ctx#runfiles) and passed to the +[`runfiles`](/rules/lib/builtins/runfiles) objects can be created by the `runfiles` method +on the rule context, [`ctx.runfiles`](/rules/lib/builtins/ctx#runfiles) and passed to the `runfiles` parameter on `DefaultInfo`. The executable output of [executable rules](#executable-rules) is implicitly added to the runfiles. @@ -517,7 +517,7 @@ def _example_library_impl(ctx): #### Custom providers -Providers can be defined using the [`provider`](/rules/lib/globals#provider) +Providers can be defined using the [`provider`](/rules/lib/globals/bzl#provider) function to convey rule-specific information: ```python @@ -556,7 +556,7 @@ provider instances obey certain invariants, or to give users a cleaner API for obtaining an instance. This is done by passing an `init` callback to the -[`provider`](/rules/lib/globals.html#provider) function. If this callback is given, the +[`provider`](/rules/lib/globals/bzl.html#provider) function. If this callback is given, the return type of `provider()` changes to be a tuple of two values: the provider symbol that is the ordinary return value when `init` is not used, and a "raw constructor". @@ -638,8 +638,8 @@ def make_exampleinfo(...): Executable rules define targets that can be invoked by a `bazel run` command. Test rules are a special kind of executable rule whose targets can also be invoked by a `bazel test` command. Executable and test rules are created by -setting the respective [`executable`](/rules/lib/globals#rule.executable) or -[`test`](/rules/lib/globals#rule.test) argument to `True` in the call to `rule`: +setting the respective [`executable`](/rules/lib/globals/bzl#rule.executable) or +[`test`](/rules/lib/globals/bzl#rule.test) argument to `True` in the call to `rule`: ```python example_binary = rule( @@ -662,7 +662,7 @@ have this suffix. Both kinds of rules must produce an executable output file (which may or may not be predeclared) that will be invoked by the `run` or `test` commands. To tell Bazel which of a rule's outputs to use as this executable, pass it as the -`executable` argument of a returned [`DefaultInfo`](/rules/lib/DefaultInfo) +`executable` argument of a returned [`DefaultInfo`](/rules/lib/providers/DefaultInfo) provider. That `executable` is added to the default outputs of the rule (so you don't need to pass that to both `executable` and `files`). It's also implicitly added to the [runfiles](#runfiles): @@ -678,10 +678,10 @@ def _example_binary_impl(ctx): ``` The action that generates this file must set the executable bit on the file. For -a [`ctx.actions.run`](/rules/lib/actions#run) or -[`ctx.actions.run_shell`](/rules/lib/actions#run_shell) action this should be done +a [`ctx.actions.run`](/rules/lib/builtins/actions#run) or +[`ctx.actions.run_shell`](/rules/lib/builtins/actions#run_shell) action this should be done by the underlying tool that is invoked by the action. For a -[`ctx.actions.write`](/rules/lib/actions#write) action, pass `is_executable=True`. +[`ctx.actions.write`](/rules/lib/builtins/actions#write) action, pass `is_executable=True`. As [legacy behavior](#deprecated_predeclared_outputs), executable rules have a special `ctx.outputs.executable` predeclared output. This file serves as the @@ -726,7 +726,7 @@ execution_root_relative_path = "%s/%s/%s" % ( ``` The path to a `File` under the runfiles directory corresponds to -[`File.short_path`](/rules/lib/File#short_path). +[`File.short_path`](/rules/lib/builtins/File#short_path). The binary executed directly by `bazel` is adjacent to the root of the `runfiles` directory. However, binaries called *from* the runfiles can't make @@ -751,8 +751,8 @@ In addition to [default outputs](#default_outputs), any *predeclared output* can be explicitly requested on the command line. Rules can specify predeclared outputs via [output attributes](#output_attributes). In that case, the user explicitly chooses labels for outputs when they instantiate the rule. To obtain -[`File`](/rules/lib/File) objects for output attributes, use the corresponding -attribute of [`ctx.outputs`](/rules/lib/ctx#outputs). Rules can +[`File`](/rules/lib/builtins/File) objects for output attributes, use the corresponding +attribute of [`ctx.outputs`](/rules/lib/builtins/ctx#outputs). Rules can [implicitly define predeclared outputs](#deprecated_predeclared_outputs) based on the target name as well, but this feature is deprecated. @@ -766,7 +766,7 @@ they can only be requested by appearing in the default outputs or an output group. Output groups can be specified with the -[`OutputGroupInfo`](/rules/lib/OutputGroupInfo) provider. Note that unlike many +[`OutputGroupInfo`](/rules/lib/providers/OutputGroupInfo) provider. Note that unlike many built-in providers, `OutputGroupInfo` can take parameters with arbitrary names to define output groups with that name: @@ -858,7 +858,7 @@ overhead. ### Configuration fragments Rules may access -[configuration fragments](/rules/lib/starlark-configuration-fragment) such as +[configuration fragments](/rules/lib/fragments) such as `cpp`, `java` and `jvm`. However, all required fragments must be declared in order to avoid access errors: @@ -925,7 +925,7 @@ is specified. If a rule implementation adds coverage instrumentation at build time, it needs to account for that in its implementation function. -[ctx.coverage_instrumented](/rules/lib/ctx#coverage_instrumented) returns true in +[ctx.coverage_instrumented](/rules/lib/builtins/ctx#coverage_instrumented) returns true in coverage mode if a target's sources should be instrumented: ```python @@ -936,7 +936,7 @@ if ctx.coverage_instrumented(): Logic that always needs to be on in coverage mode (whether a target's sources specifically are instrumented or not) can be conditioned on -[ctx.configuration.coverage_enabled](/rules/lib/configuration#coverage_enabled). +[ctx.configuration.coverage_enabled](/rules/lib/builtins/configuration#coverage_enabled). If the rule directly includes sources from its dependencies before compilation (such as header files), it may also need to turn on compile-time instrumentation if @@ -953,7 +953,7 @@ if (ctx.configuration.coverage_enabled and Rules also should provide information about which attributes are relevant for coverage with the `InstrumentedFilesInfo` provider, constructed using -[`coverage_common.instrumented_files_info`](/rules/lib/coverage_common#instrumented_files_info). +[`coverage_common.instrumented_files_info`](/rules/lib/toplevel/coverage_common#instrumented_files_info). The `dependency_attributes` parameter of `instrumented_files_info` should list all runtime dependency attributes, including code dependencies like `deps` and data dependencies like `data`. The `source_attributes` parameter should list the @@ -1139,7 +1139,7 @@ flag, which defaults to true. There are two **deprecated** ways of using predeclared outputs: -* The [`outputs`](/rules/lib/globals#rule.outputs) parameter of `rule` specifies +* The [`outputs`](/rules/lib/globals/bzl#rule.outputs) parameter of `rule` specifies a mapping between output attribute names and string templates for generating predeclared output labels. Prefer using non-predeclared outputs and explicitly adding outputs to `DefaultInfo.files`. Use the rule target's @@ -1155,12 +1155,12 @@ There are two **deprecated** ways of using predeclared outputs: ### Runfiles features to avoid -[`ctx.runfiles`](/rules/lib/ctx#runfiles) and the [`runfiles`](/rules/lib/runfiles) +[`ctx.runfiles`](/rules/lib/builtins/ctx#runfiles) and the [`runfiles`](/rules/lib/builtins/runfiles) type have a complex set of features, many of which are kept for legacy reasons. The following recommendations help reduce complexity: * **Avoid** use of the `collect_data` and `collect_default` modes of - [`ctx.runfiles`](/rules/lib/ctx#runfiles). These modes implicitly collect + [`ctx.runfiles`](/rules/lib/builtins/ctx#runfiles). These modes implicitly collect runfiles across certain hardcoded dependency edges in confusing ways. Instead, add files using the `files` or `transitive_files` parameters of `ctx.runfiles`, or by merging in runfiles from dependencies with @@ -1218,14 +1218,14 @@ provider): * The fields `files`, `runfiles`, `data_runfiles`, `default_runfiles`, and `executable` correspond to the same-named fields of - [`DefaultInfo`](/rules/lib/DefaultInfo). It is not allowed to specify any of + [`DefaultInfo`](/rules/lib/providers/DefaultInfo). It is not allowed to specify any of these fields while also returning a `DefaultInfo` provider. * The field `output_groups` takes a struct value and corresponds to an - [`OutputGroupInfo`](/rules/lib/OutputGroupInfo). + [`OutputGroupInfo`](/rules/lib/providers/OutputGroupInfo). -In [`provides`](/rules/lib/globals#rule.provides) declarations of rules, and in -[`providers`](/rules/lib/attr#label_list.providers) declarations of dependency +In [`provides`](/rules/lib/globals/bzl#rule.provides) declarations of rules, and in +[`providers`](/rules/lib/toplevel/attr#label_list.providers) declarations of dependency attributes, legacy providers are passed in as strings and modern providers are passed in by their `*Info` symbol. Be sure to change from strings to symbols when migrating. For complex or large rule sets where it is difficult to update diff --git a/site/en/extending/toolchains.md b/site/en/extending/toolchains.md index 4e642436b2fd28..879aed1322c6a2 100644 --- a/site/en/extending/toolchains.md +++ b/site/en/extending/toolchains.md @@ -173,7 +173,7 @@ def _bar_binary_impl(ctx): ``` `ctx.toolchains["//bar_tools:toolchain_type"]` returns the -[`ToolchainInfo` provider](/rules/lib/platform_common#ToolchainInfo) +[`ToolchainInfo` provider](/rules/lib/toplevel/platform_common#ToolchainInfo) of whatever target Bazel resolved the toolchain dependency to. The fields of the `ToolchainInfo` object are set by the underlying tool's rule; in the next section, this rule is defined such that there is a `barcinfo` field that wraps @@ -207,7 +207,7 @@ bar_binary = rule( When an optional toolchain type cannot be resolved, analysis continues, and the result of `ctx.toolchains["//bar_tools:toolchain_type"]` is `None`. -The [`config_common.toolchain_type`](/rules/lib/config_common#toolchain_type) +The [`config_common.toolchain_type`](/rules/lib/toplevel/config_common#toolchain_type) function defaults to mandatory. The following forms can be used: @@ -407,7 +407,7 @@ bar_toolchain = rule( ) ``` -The use of [`attr.label`](/rules/lib/attr#label) is the same as for a standard rule, +The use of [`attr.label`](/rules/lib/toplevel/attr#label) is the same as for a standard rule, but the meaning of the `cfg` parameter is slightly different. The dependency from a target (called the "parent") to a toolchain via toolchain @@ -486,9 +486,9 @@ platform for the current target. The available execution platforms and toolchains are gathered from the `WORKSPACE` file via -[`register_execution_platforms`](/rules/lib/globals#register_execution_platforms) +[`register_execution_platforms`](/rules/lib/globals/workspace#register_execution_platforms) and -[`register_toolchains`](/rules/lib/globals#register_toolchains). +[`register_toolchains`](/rules/lib/globals/workspace#register_toolchains). Additional execution platforms and toolchains may also be specified on the command line via [`--extra_execution_platforms`](/reference/command-line-reference#flag--extra_execution_platforms) @@ -510,7 +510,7 @@ The resolution steps are as follows. 1. If the target being built specifies the [`exec_compatible_with` attribute](/reference/be/common-definitions#common.exec_compatible_with) (or its rule definition specifies the - [`exec_compatible_with` argument](/rules/lib/globals#rule.exec_compatible_with)), + [`exec_compatible_with` argument](/rules/lib/globals/bzl#rule.exec_compatible_with)), the list of available execution platforms is filtered to remove any that do not match the execution constraints. diff --git a/site/en/external/advanced.md b/site/en/external/advanced.md index 6e4f472f6fd27c..f77df7f2efd602 100644 --- a/site/en/external/advanced.md +++ b/site/en/external/advanced.md @@ -114,7 +114,7 @@ Note: With [Bzlmod](/external/overview#bzlmod), remember to use canonical repo names here. Alternatively, use the [`--override_module`](/reference/command-line-reference#flag--override_module) flag to override a module to a local directory, similar to the -[`local_path_override`](/rules/lib/globals#local_path_override) directive in +[`local_path_override`](/rules/lib/globals/module#local_path_override) directive in `MODULE.bazel`. ## Using proxies @@ -165,8 +165,8 @@ the build, use the option `--nofetch`. For true offline builds, where a different entity supplies all needed files, Bazel supports the option `--distdir`. This flag tells Bazel to look first into the directories specified by that option when a repository rule asks Bazel to -fetch a file with [`ctx.download`](/rules/lib/repository_ctx#download) or -[`ctx.download_and_extract`](/rules/lib/repository_ctx#download_and_extract). By +fetch a file with [`ctx.download`](/rules/lib/builtins/repository_ctx#download) or +[`ctx.download_and_extract`](/rules/lib/builtins/repository_ctx#download_and_extract). By providing a hash sum of the file needed, Bazel looks for a file matching the basename of the first URL, and uses the local copy if the hash matches. diff --git a/site/en/external/extension.md b/site/en/external/extension.md index 90f5490864d322..57321acd570243 100644 --- a/site/en/external/extension.md +++ b/site/en/external/extension.md @@ -23,7 +23,7 @@ dependency graph. Extensions are hosted in Bazel modules themselves. To use an extension in a module, first add a `bazel_dep` on the module hosting the extension, and then -call the [`use_extension`](/rules/lib/globals#use_extension) built-in function +call the [`use_extension`](/rules/lib/globals/module#use_extension) built-in function to bring it into scope. Consider the following example — a snippet from a `MODULE.bazel` file to use the "maven" extension defined in the [`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external){:.external} @@ -48,7 +48,7 @@ maven.artifact(group = "com.google.guava", exclusions = ["com.google.j2objc:j2objc-annotations"]) ``` -Use the [`use_repo`](/rules/lib/globals#use_repo) directive to bring repos +Use the [`use_repo`](/rules/lib/globals/module#use_repo) directive to bring repos generated by the extension into the scope of the current module. ```python @@ -64,9 +64,9 @@ extension. ## Extension definition You can define module extensions similarly to repo rules, using the -[`module_extension`](/rules/lib/globals#module_extension) function. However, +[`module_extension`](/rules/lib/globals/bzl#module_extension) function. However, while repo rules have a number of attributes, module extensions have -[`tag_class`es](/rules/lib/globals#tag_class), each of which has a number of +[`tag_class`es](/rules/lib/globals/bzl#tag_class), each of which has a number of attributes. The tag classes define schemas for tags used by this extension. For example, the "maven" extension above might be defined like this: @@ -85,7 +85,7 @@ These declarations show that `maven.install` and `maven.artifact` tags can be specified using the specified attribute schema. The implementation function of module extensions are similar to those of repo -rules, except that they get a [`module_ctx`](/rules/lib/module_ctx) object, +rules, except that they get a [`module_ctx`](/rules/lib/builtins/module_ctx) object, which grants access to all modules using the extension and all pertinent tags. The implementation function then calls repo rules to generate repos. @@ -151,8 +151,8 @@ Taking repos generated by module extensions into consideration, there are several repo visibility rules: * A Bazel module repo can see all repos introduced in its `MODULE.bazel` file - via [`bazel_dep`](/rules/lib/globals#bazel_dep) and - [`use_repo`](/rules/lib/globals#use_repo). + via [`bazel_dep`](/rules/lib/globals/module#bazel_dep) and + [`use_repo`](/rules/lib/globals/module#use_repo). * A repo generated by a module extension can see all repos visible to the module that hosts the extension, *plus* all other repos generated by the same module extension (using the names specified in the repo rule calls as diff --git a/site/en/external/module.md b/site/en/external/module.md index d9f61c0b4a10fe..a273acb221defd 100644 --- a/site/en/external/module.md +++ b/site/en/external/module.md @@ -22,7 +22,7 @@ bazel_dep(name = "rules_cc", version = "0.0.1") bazel_dep(name = "protobuf", version = "3.19.0") ``` - +See the [full list](/rules/lib/globals/module) of directives available in `MODULE.bazel` files. To perform module resolution, Bazel starts by reading the root module's `MODULE.bazel` file, and then repeatedly requests any dependency's @@ -118,7 +118,7 @@ directly depend on. ### Single-version override -The [`single_version_override`](/rules/lib/globals#single_version_override) +The [`single_version_override`](/rules/lib/globals/module#single_version_override) serves multiple purposes: * With the `version` attribute, you can pin a dependency to a specific @@ -134,7 +134,7 @@ These attributes are all optional and can be mixed and matched with each other. ### Multiple-version override -A [`multiple_version_override`](/rules/lib/globals#multiple_version_override) +A [`multiple_version_override`](/rules/lib/globals/module#multiple_version_override) can be specified to allow multiple versions of the same module to coexist in the resolved dependency graph. @@ -169,9 +169,9 @@ the repo itself. Bazel supports the following non-registry overrides: -* [`archive_override`](/rules/lib/globals#archive_override) -* [`git_override`](/rules/lib/globals#git_override) -* [`local_path_override`](/rules/lib/globals#local_path_override) +* [`archive_override`](/rules/lib/globals/module#archive_override) +* [`git_override`](/rules/lib/globals/module#git_override) +* [`local_path_override`](/rules/lib/globals/module#local_path_override) ## Repository names and strict deps @@ -184,7 +184,7 @@ you should depend on and is subject to change at any time. The [apparent name](/external/overview#apparent_repository_name) of a repo backing a module to its direct dependents defaults to its module name, unless -the `repo_name` attribute of the [`bazel_dep`](/rules/lib/globals#bazel_dep) +the `repo_name` attribute of the [`bazel_dep`](/rules/lib/globals/module#bazel_dep) directive says otherwise. Note that this means a module can only find its direct dependencies. This helps prevent accidental breakages due to changes in transitive dependencies. diff --git a/site/en/external/overview.md b/site/en/external/overview.md index fae1c1bb6a8d0a..f497508558b705 100644 --- a/site/en/external/overview.md +++ b/site/en/external/overview.md @@ -166,7 +166,7 @@ The snippet defines a repo whose canonical name is `foo`. In the `WORKSPACE` system, by default, the canonical name of a repo is also its apparent name to all other repos. - +See the [full list](/rules/lib/globals/workspace) of functions available in `WORKSPACE` files. ### Shortcomings of the `WORKSPACE` system diff --git a/site/en/query/cquery.md b/site/en/query/cquery.md index 7cac978fb03c39..10d10d37e123de 100644 --- a/site/en/query/cquery.md +++ b/site/en/query/cquery.md @@ -389,7 +389,7 @@ This output format calls a [Starlark](/rules/language) function for each configured target in the query result, and prints the value returned by the call. The `--starlark:file` flag specifies the location of a Starlark file that defines a function named `format` with a single parameter, -`target`. This function is called for each [Target](/rules/lib/Target) +`target`. This function is called for each [Target](/rules/lib/builtins/Target) in the query result. Alternatively, for convenience, you may specify just the body of a function declared as `def format(target): return expr` by using the `--starlark:expr` flag. diff --git a/site/en/remote/rules.md b/site/en/remote/rules.md index 15ea01760b0233..16d96aedab7f81 100644 --- a/site/en/remote/rules.md +++ b/site/en/remote/rules.md @@ -136,7 +136,7 @@ remote execution: build to fail on the remote execution platform as Bazel will not be able to locate them. Instead, create symlinks using standard build actions so that the symlinked tools and libraries are accessible from Bazel's `runfiles` - tree. Do not use [`repository_ctx.symlink`](/rules/lib/repository_ctx#symlink) + tree. Do not use [`repository_ctx.symlink`](/rules/lib/builtins/repository_ctx#symlink) to symlink target files outside of the external repo directory. * **Mutating the host platform.** Avoid creating files outside of the Bazel diff --git a/site/en/remote/workspace.md b/site/en/remote/workspace.md index aa65553a09dabf..b0afda3a79f157 100644 --- a/site/en/remote/workspace.md +++ b/site/en/remote/workspace.md @@ -27,7 +27,7 @@ external workspaces, but they are rich enough to allow arbitrary processing to happen in the process. All related commands are happening locally and can be a potential source of non-hermeticity. Usually non-hermetic behavior is introduced through -[`repository_ctx`](/rules/lib/repository_ctx) which allows interacting +[`repository_ctx`](/rules/lib/builtins/repository_ctx) which allows interacting with the host machine. Starting with Bazel 0.18, you can get a log of some potentially non-hermetic @@ -98,7 +98,7 @@ To find what was executed during workspace initialization: The log consists of [WorkspaceEvent](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/bazel/debug/workspace_log.proto?q=WorkspaceEvent) messages outlining certain potentially non-hermetic actions performed on a -[`repository_ctx`](/rules/lib/repository_ctx). +[`repository_ctx`](/rules/lib/builtins/repository_ctx). The actions that have been highlighted as potentially non-hermetic are as follows: diff --git a/site/en/rules/language.md b/site/en/rules/language.md index 3a47d4a4b11aa9..76c33715fa726a 100644 --- a/site/en/rules/language.md +++ b/site/en/rules/language.md @@ -9,7 +9,7 @@ Book: /_book.yaml This page is an overview of [Starlark](https://github.com/bazelbuild/starlark), formerly known as Skylark, the language used in Bazel. For a complete list of -functions and types, see the [Bazel API reference](/rules/lib/starlark-overview). +functions and types, see the [Bazel API reference](/rules/lib/overview). For more information about the language, see [Starlark's GitHub repo](https://github.com/bazelbuild/starlark/). @@ -100,7 +100,7 @@ definitions for constants, rules, macros, and functions. [Native functions](/reference/be/functions) and [native rules]( /reference/be/overview#language-specific-native-rules) are global symbols in `BUILD` files. `bzl` files need to load them using the [`native` module]( -https://bazel.build/rules/lib/native). +/rules/lib/toplevel/native). There are two syntactic restrictions in `BUILD` files: 1) declaring functions is illegal, and 2) `*args` and `**kwargs` arguments are not allowed. diff --git a/site/en/tutorials/ccp-toolchain-config.md b/site/en/tutorials/ccp-toolchain-config.md index 5c5797cdaa75df..df2d47e0bd0fb1 100644 --- a/site/en/tutorials/ccp-toolchain-config.md +++ b/site/en/tutorials/ccp-toolchain-config.md @@ -137,7 +137,7 @@ slightly between different versions of clang. ``` Bazel discovered that the `--crosstool_top` flag points to a rule that - doesn't provide the necessary [`ToolchainInfo`](/rules/lib/ToolchainInfo) + doesn't provide the necessary [`ToolchainInfo`](/rules/lib/providers/ToolchainInfo) provider. So you need to point `--crosstool_top` to a rule that does provide `ToolchainInfo` - that is the `cc_toolchain_suite` rule. In the `toolchain/BUILD` file, replace the empty filegroup with the following: @@ -328,7 +328,7 @@ slightly between different versions of clang. Bazel needs to know where to search for included headers. There are multiple ways to solve this, such as using the `includes` attribute of `cc_binary`, but here this is solved at the toolchain level with the - [`cxx_builtin_include_directories`](/rules/lib/cc_common#create_cc_toolchain_config_info) + [`cxx_builtin_include_directories`](/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info) parameter of `cc_common.create_cc_toolchain_config_info`. Beware that if you are using a different version of `clang`, the include path will be different. These paths may also be different depending on the distribution. diff --git a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java index 7b9e1fc6c8a730..1d92e0ac9190eb 100644 --- a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java +++ b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java @@ -14,15 +14,17 @@ package com.google.devtools.build.docgen; import com.google.common.collect.ImmutableList; +import com.google.common.collect.ImmutableMap; +import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category; import com.google.devtools.build.docgen.builtin.BuiltinProtos.ApiContext; import com.google.devtools.build.docgen.builtin.BuiltinProtos.Builtins; import com.google.devtools.build.docgen.builtin.BuiltinProtos.Callable; import com.google.devtools.build.docgen.builtin.BuiltinProtos.Param; import com.google.devtools.build.docgen.builtin.BuiltinProtos.Type; import com.google.devtools.build.docgen.builtin.BuiltinProtos.Value; -import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc; import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc; import com.google.devtools.build.docgen.starlark.StarlarkDocExpander; +import com.google.devtools.build.docgen.starlark.StarlarkDocPage; import com.google.devtools.build.docgen.starlark.StarlarkMethodDoc; import com.google.devtools.build.docgen.starlark.StarlarkParamDoc; import com.google.devtools.common.options.OptionsParser; @@ -33,6 +35,7 @@ import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; +import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.Map.Entry; @@ -51,51 +54,43 @@ public class ApiExporter { private static void appendTypes( - Builtins.Builder builtins, - Map types, - List nativeRules) + Builtins.Builder builtins, StarlarkDocPage docPage, List nativeRules) throws BuildEncyclopediaDocException { - - for (Entry modEntry : types.entrySet()) { - StarlarkBuiltinDoc mod = modEntry.getValue(); - - Type.Builder type = Type.newBuilder(); - type.setName(mod.getName()); - type.setDoc(mod.getDocumentation()); - for (StarlarkMethodDoc meth : mod.getJavaMethods()) { - // Constructors are exported as global symbols. - if (!(meth instanceof StarlarkConstructorMethodDoc)) { - Value.Builder value = collectMethodInfo(meth); + Type.Builder type = Type.newBuilder(); + type.setName(docPage.getName()); + type.setDoc(docPage.getDocumentation()); + for (StarlarkMethodDoc meth : docPage.getJavaMethods()) { + // Constructors are exported as global symbols. + if (!(meth instanceof StarlarkConstructorMethodDoc)) { + Value.Builder value = collectMethodInfo(meth); + if (type.getName().equals("native")) { // Methods from the native package are available as top level functions in BUILD files. - if (mod.getName().equals("native")) { - value.setApiContext(ApiContext.BUILD); - builtins.addGlobal(value); + value.setApiContext(ApiContext.BUILD); + builtins.addGlobal(value); - value.setApiContext(ApiContext.BZL); - type.addField(value); - } else { - value.setApiContext(ApiContext.ALL); - type.addField(value); - } + value.setApiContext(ApiContext.BZL); + type.addField(value); + } else { + value.setApiContext(ApiContext.ALL); + type.addField(value); } } - // Native rules are available in BZL file as methods of the native package. - if (mod.getName().equals("native")) { - for (RuleDocumentation rule : nativeRules) { - Value.Builder field = collectRuleInfo(rule); - field.setApiContext(ApiContext.BZL); - type.addField(field); - } + } + if (type.getName().equals("native")) { + for (RuleDocumentation rule : nativeRules) { + Value.Builder field = collectRuleInfo(rule); + field.setApiContext(ApiContext.BZL); + type.addField(field); } - builtins.addType(type); } + builtins.addType(type); } private static void appendGlobals( Builtins.Builder builtins, Map globals, Map globalToDoc, - Map types, + Map typeNameToConstructor, ApiContext context) { for (Entry entry : globals.entrySet()) { String name = entry.getKey(); @@ -122,12 +117,9 @@ private static void appendGlobals( StarlarkMethod annotation = StarlarkAnnotations.getStarlarkMethod(selfCallMethod); value = valueFromAnnotation(annotation); // For constructors, we can also set the return type. - StarlarkBuiltinDoc doc = types.get(entry.getKey()); - if (doc != null) { - StarlarkConstructorMethodDoc constructor = doc.getConstructor(); - if (constructor != null && value.hasCallable()) { - value.getCallableBuilder().setReturnType(constructor.getReturnType()); - } + StarlarkConstructorMethodDoc constructor = typeNameToConstructor.get(entry.getKey()); + if (constructor != null && value.hasCallable()) { + value.getCallableBuilder().setReturnType(constructor.getReturnType()); } } else { value.setName(name); @@ -353,20 +345,32 @@ public static void main(String[] args) { options.provider, options.inputDirs, options.denylist); - Map types = symbols.getTypes(); + ImmutableMap> allDocPages = symbols.getAllDocPages(); Builtins.Builder builtins = Builtins.newBuilder(); - StarlarkBuiltinDoc globals = types.get("globals"); + ImmutableList globalPages = allDocPages.get(Category.GLOBAL_FUNCTION); Map globalToDoc = new HashMap<>(); - if (globals != null) { - for (StarlarkMethodDoc meth : globals.getJavaMethods()) { + for (StarlarkDocPage globalPage : globalPages) { + for (StarlarkMethodDoc meth : globalPage.getJavaMethods()) { globalToDoc.put(meth.getShortName(), meth); } } - appendTypes(builtins, types, symbols.getNativeRules()); - appendGlobals(builtins, symbols.getGlobals(), globalToDoc, types, ApiContext.ALL); - appendGlobals(builtins, symbols.getBzlGlobals(), globalToDoc, types, ApiContext.BZL); + Iterator typesIterator = + allDocPages.entrySet().stream() + .filter(e -> !e.getKey().equals(Category.GLOBAL_FUNCTION)) + .flatMap(e -> e.getValue().stream()) + .iterator(); + Map typeNameToConstructor = new HashMap<>(); + while (typesIterator.hasNext()) { + StarlarkDocPage typeDocPage = typesIterator.next(); + appendTypes(builtins, typeDocPage, symbols.getNativeRules()); + typeNameToConstructor.put(typeDocPage.getName(), typeDocPage.getConstructor()); + } + appendGlobals( + builtins, symbols.getGlobals(), globalToDoc, typeNameToConstructor, ApiContext.ALL); + appendGlobals( + builtins, symbols.getBzlGlobals(), globalToDoc, typeNameToConstructor, ApiContext.BZL); appendNativeRules(builtins, symbols.getNativeRules()); writeBuiltins(options.outputFile, builtins); 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 825f87500d6eef..0917e84a33e1ea 100644 --- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java +++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java @@ -39,8 +39,6 @@ public class DocgenConsts { public static final String STARLARK_LIBRARY_TEMPLATE = "com/google/devtools/build/docgen/templates/starlark-library.vm"; - public static final String STARLARK_NAV_TEMPLATE = - "com/google/devtools/build/docgen/templates/starlark-nav.vm"; public static final String STARLARK_MODULE_CATEGORY_TEMPLATE = "com/google/devtools/build/docgen/templates/starlark-category.vm"; public static final String STARLARK_OVERVIEW_TEMPLATE = diff --git a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java index c14e5da907c7b0..df6efd321f9479 100644 --- a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java +++ b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java @@ -14,51 +14,47 @@ package com.google.devtools.build.docgen; import com.google.common.base.Preconditions; +import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.common.collect.Iterables; -import com.google.devtools.build.docgen.annot.DocCategory; +import com.google.common.collect.Maps; +import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category; import com.google.devtools.build.docgen.annot.GlobalMethods; +import com.google.devtools.build.docgen.annot.GlobalMethods.Environment; import com.google.devtools.build.docgen.annot.StarlarkConstructor; import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc; import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc; import com.google.devtools.build.docgen.starlark.StarlarkDocExpander; +import com.google.devtools.build.docgen.starlark.StarlarkDocPage; +import com.google.devtools.build.docgen.starlark.StarlarkGlobalsDoc; import com.google.devtools.build.docgen.starlark.StarlarkJavaMethodDoc; import com.google.devtools.build.lib.util.Classpath; import com.google.devtools.build.lib.util.Classpath.ClassPathException; import java.lang.reflect.Method; +import java.text.Collator; +import java.util.Comparator; +import java.util.EnumMap; +import java.util.HashMap; +import java.util.Locale; import java.util.Map; -import java.util.TreeMap; -import javax.annotation.Nullable; import net.starlark.java.annot.StarlarkAnnotations; import net.starlark.java.annot.StarlarkBuiltin; import net.starlark.java.annot.StarlarkMethod; import net.starlark.java.eval.Starlark; import net.starlark.java.eval.StarlarkSemantics; -import net.starlark.java.eval.StarlarkValue; /** A helper class that collects Starlark module documentation. */ final class StarlarkDocumentationCollector { - @StarlarkBuiltin( - name = "globals", - category = DocCategory.TOP_LEVEL_MODULE, - doc = "Objects, functions and modules registered in the global environment.") - private static final class TopLevelModule implements StarlarkValue {} - private StarlarkDocumentationCollector() {} - /** Returns the StarlarkBuiltin annotation for the top-level Starlark module. */ - public static StarlarkBuiltin getTopLevelModule() { - return TopLevelModule.class.getAnnotation(StarlarkBuiltin.class); - } - - private static ImmutableMap all; + private static ImmutableMap> all; - /** Applies {@link #collectModules} to all Bazel and Starlark classes. */ - static synchronized ImmutableMap getAllModules( + /** Applies {@link #collectDocPages} to all Bazel and Starlark classes. */ + static synchronized ImmutableMap> getAllDocPages( StarlarkDocExpander expander) throws ClassPathException { if (all == null) { all = - collectModules( + collectDocPages( Iterables.concat( /*Bazel*/ Classpath.findClasses("com/google/devtools/build"), /*Starlark*/ Classpath.findClasses("net/starlark/java")), @@ -71,27 +67,16 @@ static synchronized ImmutableMap getAllModules( * Collects the documentation for all Starlark modules comprised of the given classes and returns * a map from the name of each Starlark module to its documentation. */ - static ImmutableMap collectModules( + static ImmutableMap> collectDocPages( Iterable> classes, StarlarkDocExpander expander) { - Map modules = new TreeMap<>(); - // The top level module first. - // (This is a special case of {@link StarlarkBuiltinDoc} as it has no object name). - StarlarkBuiltin topLevelModule = getTopLevelModule(); - modules.put( - topLevelModule.name(), - new StarlarkBuiltinDoc( - topLevelModule, - /*title=*/ "Globals", - TopLevelModule.class, - expander, - /*isTopLevel=*/ true)); + Map> pages = new EnumMap<>(Category.class); + for (Category category : Category.values()) { + pages.put(category, new HashMap<>()); + } - // Creating module documentation is done in three passes. // 1. Add all classes/interfaces annotated with @StarlarkBuiltin with documented = true. for (Class candidateClass : classes) { - if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)) { - collectStarlarkModule(candidateClass, modules, expander); - } + collectStarlarkBuiltin(candidateClass, pages, expander); } // 2. Add all object methods and global functions. @@ -112,175 +97,177 @@ static ImmutableMap collectModules( // Note that BuiltinFunction doesn't actually have getJavaMethod. // for (Class candidateClass : classes) { - if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)) { - collectModuleMethods(candidateClass, modules, expander); - } - if (candidateClass.isAnnotationPresent(GlobalMethods.class) - || candidateClass.getName().equals("net.starlark.java.eval.MethodLibrary")) { - collectDocumentedMethods(candidateClass, modules, expander); - } + collectBuiltinMethods(candidateClass, pages, expander); + collectGlobalMethods(candidateClass, pages, expander); } // 3. Add all constructors. for (Class candidateClass : classes) { - if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class) - || candidateClass.isAnnotationPresent(GlobalMethods.class)) { - collectConstructorMethods(candidateClass, modules, expander); - } + collectConstructorMethods(candidateClass, pages, expander); } - return ImmutableMap.copyOf(modules); + return ImmutableMap.copyOf( + Maps.transformValues( + pages, + pagesInCategory -> + ImmutableList.sortedCopyOf( + Comparator.comparing( + StarlarkDocPage::getTitle, Collator.getInstance(Locale.US)), + pagesInCategory.values()))); } /** - * Returns the {@link StarlarkBuiltinDoc} entry representing the collection of top level - * functions. (This is a special case of {@link StarlarkBuiltinDoc} as it has no object name). + * Adds a single {@link StarlarkDocPage} entry to {@code pages} representing the given {@code + * builtinClass}, if it is a documented builtin. */ - private static StarlarkBuiltinDoc getTopLevelModuleDoc(Map modules) { - return modules.get(getTopLevelModule().name()); - } - - /** - * Adds a single {@link StarlarkBuiltinDoc} entry to {@code modules} representing the given {@code - * moduleClass}, if it is a documented module. - */ - private static void collectStarlarkModule( - Class moduleClass, Map modules, StarlarkDocExpander expander) { - if (moduleClass.equals(TopLevelModule.class)) { - // The top level module doc is a special case and is handled separately. + private static void collectStarlarkBuiltin( + Class builtinClass, + Map> pages, + StarlarkDocExpander expander) { + StarlarkBuiltin starlarkBuiltin = builtinClass.getAnnotation(StarlarkBuiltin.class); + if (starlarkBuiltin == null || !starlarkBuiltin.documented()) { return; } - StarlarkBuiltin moduleAnnotation = - Preconditions.checkNotNull(moduleClass.getAnnotation(StarlarkBuiltin.class)); + Map pagesInCategory = pages.get(Category.of(starlarkBuiltin)); + StarlarkDocPage existingPage = pagesInCategory.get(starlarkBuiltin.name()); + if (existingPage == null) { + pagesInCategory.put( + starlarkBuiltin.name(), new StarlarkBuiltinDoc(starlarkBuiltin, builtinClass, expander)); + return; + } - if (moduleAnnotation.documented()) { - StarlarkBuiltinDoc previousModuleDoc = modules.get(moduleAnnotation.name()); - if (previousModuleDoc == null) { - modules.put( - moduleAnnotation.name(), - new StarlarkBuiltinDoc( - moduleAnnotation, moduleAnnotation.name(), moduleClass, expander)); - } else { - // Handle a strange corner-case: If moduleClass has a subclass which is also - // annotated with {@link StarlarkBuiltin} with the same name, and also has the same - // module-level docstring, then the subclass takes precedence. - // (This is useful if one module is a "common" stable module, and its subclass is - // an experimental module that also supports all stable methods.) - validateCompatibleModules(previousModuleDoc.getClassObject(), moduleClass); + // Handle a strange corner-case: If builtinClass has a subclass which is also + // annotated with @StarlarkBuiltin with the same name, and also has the same + // docstring, then the subclass takes precedence. + // (This is useful if one class is the "common" one with stable methods, and its subclass is + // an experimental class that also supports all stable methods.) + Preconditions.checkState( + existingPage instanceof StarlarkBuiltinDoc, + "the same name %s is assigned to both a global method environment and a builtin type", + starlarkBuiltin.name()); + Class clazz = ((StarlarkBuiltinDoc) existingPage).getClassObject(); + validateCompatibleBuiltins(clazz, builtinClass); - if (previousModuleDoc.getClassObject().isAssignableFrom(moduleClass)) { - // The new module is a subclass of the old module, so use the subclass. - modules.put( - moduleAnnotation.name(), - new StarlarkBuiltinDoc( - moduleAnnotation, /*title=*/ moduleAnnotation.name(), moduleClass, expander)); - } - } + if (clazz.isAssignableFrom(builtinClass)) { + // The new builtin is a subclass of the old builtin, so use the subclass. + pagesInCategory.put( + starlarkBuiltin.name(), new StarlarkBuiltinDoc(starlarkBuiltin, builtinClass, expander)); } } - /** - * Validate that it is acceptable that the given module classes with the same module name - * co-exist. - */ - private static void validateCompatibleModules(Class one, Class two) { - StarlarkBuiltin moduleOne = one.getAnnotation(StarlarkBuiltin.class); - StarlarkBuiltin moduleTwo = two.getAnnotation(StarlarkBuiltin.class); + /** Validate that it is acceptable that the given builtin classes with the same name co-exist. */ + private static void validateCompatibleBuiltins(Class one, Class two) { + StarlarkBuiltin builtinOne = one.getAnnotation(StarlarkBuiltin.class); + StarlarkBuiltin builtinTwo = two.getAnnotation(StarlarkBuiltin.class); if (one.isAssignableFrom(two) || two.isAssignableFrom(one)) { - if (!moduleOne.doc().equals(moduleTwo.doc())) { + if (!builtinOne.doc().equals(builtinTwo.doc())) { throw new IllegalStateException( String.format( - "%s and %s are related modules but have mismatching documentation for '%s'", - one, two, moduleOne.name())); + "%s and %s are related builtins but have mismatching documentation for '%s'", + one, two, builtinOne.name())); } } else { throw new IllegalStateException( String.format( - "%s and %s are unrelated modules with documentation for '%s'", - one, two, moduleOne.name())); + "%s and %s are unrelated builtins with documentation for '%s'", + one, two, builtinOne.name())); } } - private static void collectModuleMethods( - Class moduleClass, Map modules, StarlarkDocExpander expander) { - StarlarkBuiltin moduleAnnotation = - Preconditions.checkNotNull(moduleClass.getAnnotation(StarlarkBuiltin.class)); + private static void collectBuiltinMethods( + Class builtinClass, + Map> pages, + StarlarkDocExpander expander) { + StarlarkBuiltin starlarkBuiltin = builtinClass.getAnnotation(StarlarkBuiltin.class); - if (moduleAnnotation.documented()) { - StarlarkBuiltinDoc moduleDoc = - Preconditions.checkNotNull(modules.get(moduleAnnotation.name())); + if (starlarkBuiltin == null || !starlarkBuiltin.documented()) { + return; + } + StarlarkBuiltinDoc builtinDoc = + (StarlarkBuiltinDoc) pages.get(Category.of(starlarkBuiltin)).get(starlarkBuiltin.name()); - if (moduleClass == moduleDoc.getClassObject()) { - for (Map.Entry entry : - Starlark.getMethodAnnotations(moduleClass).entrySet()) { - // Collect methods that aren't directly constructors (i.e. have the @StarlarkConstructor - // annotation). - // Struct fields that return a type that has @StarlarkConstructor are a bit special: - // they're visited here because they're seen as an attribute of the module, but act more - // like a reference to the type they construct - if (!entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) { - Method javaMethod = entry.getKey(); - StarlarkMethod starlarkMethod = entry.getValue(); - // Handle struct fields that return a Starlark constructor so that - // documentation can link to the constructed type. - if (starlarkMethod.structField()) { - Method constructor = getSelfCallConstructorMethod(javaMethod.getReturnType()); - if (constructor != null) { - javaMethod = constructor; - } - } - moduleDoc.addMethod( - new StarlarkJavaMethodDoc( - moduleDoc.getName(), javaMethod, starlarkMethod, expander)); - } + if (builtinClass != builtinDoc.getClassObject()) { + return; + } + for (Map.Entry entry : + Starlark.getMethodAnnotations(builtinClass).entrySet()) { + // Collect methods that aren't directly constructors (i.e. have the @StarlarkConstructor + // annotation). + if (entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) { + continue; + } + Method javaMethod = entry.getKey(); + StarlarkMethod starlarkMethod = entry.getValue(); + // Struct fields that return a type that has @StarlarkConstructor are a bit special: + // they're visited here because they're seen as an attribute of the module, but act more + // like a reference to the type they construct. + // TODO(wyv): does this actually happen??? + if (starlarkMethod.structField()) { + Method selfCall = + Starlark.getSelfCallMethod(StarlarkSemantics.DEFAULT, javaMethod.getReturnType()); + if (selfCall != null && selfCall.isAnnotationPresent(StarlarkConstructor.class)) { + javaMethod = selfCall; } } + builtinDoc.addMethod( + new StarlarkJavaMethodDoc(builtinDoc.getName(), javaMethod, starlarkMethod, expander)); } } - @Nullable - private static Method getSelfCallConstructorMethod(Class objectClass) { - Method selfCallMethod = Starlark.getSelfCallMethod(StarlarkSemantics.DEFAULT, objectClass); - if (selfCallMethod != null && selfCallMethod.isAnnotationPresent(StarlarkConstructor.class)) { - return selfCallMethod; - } - return null; - } - /** * Adds {@link StarlarkJavaMethodDoc} entries to the top level module, one for - * each @StarlarkMethod method defined in the given @GlobalMethods class {@code moduleClass}. + * each @StarlarkMethod method defined in the given @GlobalMethods class {@code clazz}. */ - private static void collectDocumentedMethods( - Class moduleClass, Map modules, StarlarkDocExpander expander) { - StarlarkBuiltinDoc topLevelModuleDoc = getTopLevelModuleDoc(modules); + private static void collectGlobalMethods( + Class clazz, + Map> pages, + StarlarkDocExpander expander) { + GlobalMethods globalMethods = clazz.getAnnotation(GlobalMethods.class); - for (Map.Entry entry : - Starlark.getMethodAnnotations(moduleClass).entrySet()) { - // Only add non-constructor global library methods. Constructors are added later. - if (!entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) { - topLevelModuleDoc.addMethod( - new StarlarkJavaMethodDoc("", entry.getKey(), entry.getValue(), expander)); + if (globalMethods == null && !clazz.getName().equals("net.starlark.java.eval.MethodLibrary")) { + return; + } + + Environment[] environments = + globalMethods == null ? new Environment[] {Environment.ALL} : globalMethods.environment(); + for (Environment environment : environments) { + StarlarkDocPage page = + pages + .get(Category.GLOBAL_FUNCTION) + .computeIfAbsent( + environment.getTitle(), title -> new StarlarkGlobalsDoc(environment, expander)); + for (Map.Entry entry : + Starlark.getMethodAnnotations(clazz).entrySet()) { + // Only add non-constructor global library methods. Constructors are added later. + // TODO(wyv): add a redirect instead + if (!entry.getKey().isAnnotationPresent(StarlarkConstructor.class)) { + page.addMethod(new StarlarkJavaMethodDoc("", entry.getKey(), entry.getValue(), expander)); + } } } } private static void collectConstructor( - Map modules, Method method, StarlarkDocExpander expander) { - Preconditions.checkNotNull(method.getAnnotation(StarlarkConstructor.class)); + Map> pages, + Method method, + StarlarkDocExpander expander) { + if (!method.isAnnotationPresent(StarlarkConstructor.class)) { + return; + } - StarlarkBuiltin builtinType = StarlarkAnnotations.getStarlarkBuiltin(method.getReturnType()); - if (builtinType == null || !builtinType.documented()) { + StarlarkBuiltin starlarkBuiltin = + StarlarkAnnotations.getStarlarkBuiltin(method.getReturnType()); + if (starlarkBuiltin == null || !starlarkBuiltin.documented()) { // The class of the constructed object type has no documentation, so no place to add // constructor information. return; } StarlarkMethod methodAnnot = Preconditions.checkNotNull(method.getAnnotation(StarlarkMethod.class)); - StarlarkBuiltinDoc doc = modules.get(builtinType.name()); + StarlarkDocPage doc = pages.get(Category.of(starlarkBuiltin)).get(starlarkBuiltin.name()); doc.setConstructor( - new StarlarkConstructorMethodDoc(builtinType.name(), method, methodAnnot, expander)); + new StarlarkConstructorMethodDoc(starlarkBuiltin.name(), method, methodAnnot, expander)); } /** @@ -297,16 +284,20 @@ private static void collectConstructor( * documentation) */ private static void collectConstructorMethods( - Class moduleClass, Map modules, StarlarkDocExpander expander) { - Method selfCallConstructor = getSelfCallConstructorMethod(moduleClass); - if (selfCallConstructor != null) { - collectConstructor(modules, selfCallConstructor, expander); + Class clazz, + Map> pages, + StarlarkDocExpander expander) { + if (!clazz.isAnnotationPresent(StarlarkBuiltin.class) + && !clazz.isAnnotationPresent(GlobalMethods.class)) { + return; + } + Method selfCall = Starlark.getSelfCallMethod(StarlarkSemantics.DEFAULT, clazz); + if (selfCall != null) { + collectConstructor(pages, selfCall, expander); } - for (Method method : Starlark.getMethodAnnotations(moduleClass).keySet()) { - if (method.isAnnotationPresent(StarlarkConstructor.class)) { - collectConstructor(modules, method, expander); - } + for (Method method : Starlark.getMethodAnnotations(clazz).keySet()) { + collectConstructor(pages, method, expander); } } } diff --git a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java index a7ac11d147bb03..be8f98f4509262 100644 --- a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java +++ b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationProcessor.java @@ -14,30 +14,22 @@ package com.google.devtools.build.docgen; import com.google.common.collect.ImmutableList; +import com.google.common.collect.ImmutableMap; import com.google.devtools.build.docgen.annot.DocCategory; -import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc; import com.google.devtools.build.docgen.starlark.StarlarkDocExpander; -import com.google.devtools.build.docgen.starlark.StarlarkMethodDoc; +import com.google.devtools.build.docgen.starlark.StarlarkDocPage; import com.google.devtools.build.lib.util.Classpath.ClassPathException; import java.io.File; import java.io.IOException; -import java.text.Collator; -import java.util.ArrayList; -import java.util.Collections; +import java.nio.file.Files; +import java.nio.file.Path; import java.util.HashMap; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Locale; import java.util.Map; -import java.util.TreeMap; import net.starlark.java.annot.StarlarkBuiltin; /** A class to assemble documentation for Starlark. */ public final class StarlarkDocumentationProcessor { - private static final ImmutableList GLOBAL_CATEGORIES = - ImmutableList.of(Category.TOP_LEVEL_MODULE); - private StarlarkDocumentationProcessor() {} /** Generates the Starlark documentation to the given output directory. */ @@ -59,152 +51,63 @@ public static void generateDocumentation(String outputDir, String... args) StarlarkDocExpander expander = new StarlarkDocExpander(new RuleLinkExpander(/* singlePage= */ false, linkMap)); - Map modules = - new TreeMap<>(StarlarkDocumentationCollector.getAllModules(expander)); - - // Generate the top level module first in the doc - StarlarkBuiltinDoc topLevelModule = - modules.remove(StarlarkDocumentationCollector.getTopLevelModule().name()); - writePage(outputDir, topLevelModule); - - // Use a LinkedHashMap to preserve ordering of categories, as the output iterates over - // this map's entry set to determine category ordering. - Map> modulesByCategory = new LinkedHashMap<>(); - for (Category c : Category.values()) { - modulesByCategory.put(c, new ArrayList()); - } - - modulesByCategory.get(Category.of(topLevelModule.getAnnotation())).add(topLevelModule); - - for (StarlarkBuiltinDoc module : modules.values()) { - if (module.getAnnotation().documented()) { - writePage(outputDir, module); - modulesByCategory.get(Category.of(module.getAnnotation())).add(module); - } - } - Collator us = Collator.getInstance(Locale.US); - for (List module : modulesByCategory.values()) { - Collections.sort(module, (doc1, doc2) -> us.compare(doc1.getTitle(), doc2.getTitle())); - } - writeCategoryPage(Category.CORE, outputDir, modulesByCategory, expander); - writeCategoryPage(Category.CONFIGURATION_FRAGMENT, outputDir, modulesByCategory, expander); - writeCategoryPage(Category.BUILTIN, outputDir, modulesByCategory, expander); - writeCategoryPage(Category.PROVIDER, outputDir, modulesByCategory, expander); - writeNavPage(outputDir, modulesByCategory.get(Category.TOP_LEVEL_MODULE)); - - // In the code, there are two StarlarkModuleCategory instances that have no heading: - // TOP_LEVEL_TYPE and NONE. + ImmutableMap> allPages = + StarlarkDocumentationCollector.getAllDocPages(expander); - // TOP_LEVEL_TYPE also contains the "global" module. - // We remove both categories and the "global" module from the map and display them manually: - // - Methods in the "global" module are displayed under "Global Methods and Constants". - // - Modules in both categories are displayed under "Global Modules" (except for the global - // module itself). - List globalFunctions = new ArrayList<>(); - List globalConstants = new ArrayList<>(); - StarlarkBuiltinDoc globalModule = findGlobalModule(modulesByCategory); - for (StarlarkMethodDoc method : globalModule.getMethods()) { - if (method.documented()) { - if (method.isCallable()) { - globalFunctions.add(method.getName()); - } else { - globalConstants.add(method.getName()); - } + for (var categoryAndPages : allPages.entrySet()) { + writeCategoryPage( + categoryAndPages.getKey(), outputDir, categoryAndPages.getValue(), expander); + for (StarlarkDocPage page : categoryAndPages.getValue()) { + writePage(outputDir, categoryAndPages.getKey(), page); } } - List globalModules = new ArrayList<>(); - for (Category globalCategory : GLOBAL_CATEGORIES) { - for (StarlarkBuiltinDoc module : modulesByCategory.remove(globalCategory)) { - if (!module.getName().equals(globalModule.getName())) { - globalModules.add(module); - } - } - } - - Collections.sort(globalModules, (doc1, doc2) -> us.compare(doc1.getName(), doc2.getName())); - writeOverviewPage( - outputDir, - globalModule.getName(), - globalFunctions, - globalConstants, - globalModules, - modulesByCategory); + writeOverviewPage(outputDir, allPages); if (shouldCreateToc(options)) { - writeTableOfContents(outputDir, globalModules, modulesByCategory); - } - } - - private static StarlarkBuiltinDoc findGlobalModule( - Map> modulesByCategory) { - List topLevelModules = modulesByCategory.get(Category.TOP_LEVEL_MODULE); - String globalModuleName = StarlarkDocumentationCollector.getTopLevelModule().name(); - for (StarlarkBuiltinDoc module : topLevelModules) { - if (module.getName().equals(globalModuleName)) { - return module; - } + writeTableOfContents(outputDir, allPages); } - - throw new IllegalStateException("No globals module in the top level category."); } - private static void writePage(String outputDir, StarlarkBuiltinDoc module) throws IOException { - File starlarkDocPath = new File(outputDir + "/" + module.getName() + ".html"); + private static void writePage(String outputDir, Category category, StarlarkDocPage docPage) + throws IOException { + File starlarkDocPath = + new File(String.format("%s/%s/%s.html", outputDir, category.getPath(), docPage.getName())); Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_LIBRARY_TEMPLATE); - page.add("module", module); + page.add("page", docPage); page.write(starlarkDocPath); } private static void writeCategoryPage( Category category, String outputDir, - Map> modules, + ImmutableList allPages, StarlarkDocExpander expander) throws IOException { - File starlarkDocPath = - new File(String.format("%s/starlark-%s.html", outputDir, category.getTemplateIdentifier())); + Files.createDirectories(Path.of(outputDir, category.getPath())); + + File starlarkDocPath = new File(String.format("%s/%s.html", outputDir, category.getPath())); Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_MODULE_CATEGORY_TEMPLATE); page.add("category", category); - page.add("modules", modules.get(category)); + page.add("allPages", allPages); page.add("description", expander.expand(category.description)); page.write(starlarkDocPath); } - private static void writeNavPage(String outputDir, List navModules) - throws IOException { - File navFile = new File(outputDir + "/starlark-nav.html"); - Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_NAV_TEMPLATE); - page.add("modules", navModules); - page.write(navFile); - } - private static void writeOverviewPage( - String outputDir, - String globalModuleName, - List globalFunctions, - List globalConstants, - List globalModules, - Map> modulesPerCategory) + String outputDir, ImmutableMap> allPages) throws IOException { - File starlarkDocPath = new File(outputDir + "/starlark-overview.html"); + File starlarkDocPath = new File(outputDir + "/overview.html"); Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_OVERVIEW_TEMPLATE); - page.add("global_name", globalModuleName); - page.add("global_functions", globalFunctions); - page.add("global_constants", globalConstants); - page.add("global_modules", globalModules); - page.add("modules", modulesPerCategory); + page.add("allPages", allPages); page.write(starlarkDocPath); } private static void writeTableOfContents( - String outputDir, - List globalModules, - Map> modulesPerCategory) + String outputDir, ImmutableMap> allPages) throws IOException { File starlarkDocPath = new File(outputDir + "/_toc.yaml"); Page page = TemplateEngine.newPage(DocgenConsts.STARLARK_TOC_TEMPLATE); - page.add("global_modules", globalModules); - page.add("modules", modulesPerCategory); + page.add("allPages", allPages); page.write(starlarkDocPath); } @@ -232,37 +135,56 @@ private static boolean shouldCreateToc(Map options) { * accessed by templates, using reflection. */ public enum Category { + GLOBAL_FUNCTION( + "Global functions", + "globals", + "This section lists the global functions available in Starlark. The list of available" + + " functions differs depending on the file type (whether a BUILD file, or a .bzl file," + + " etc)."), + CONFIGURATION_FRAGMENT( "Configuration Fragments", + "fragments", "Configuration fragments give rules access to " - + "language-specific parts of " + + "language-specific parts of " + "configuration. " + "

Rule implementations can get them using " - + "ctx." + + "ctx." + "fragments.[fragment name]"), PROVIDER( "Providers", + "providers", "This section lists providers available on built-in rules. See the Rules page for more on" - + " providers."), + + " providers. These symbols are available only in .bzl files."), - BUILTIN("Built-in Types", "This section lists types of Starlark objects."), + BUILTIN( + "Built-in Types", + "builtins", + "This section lists types of Starlark objects. With some exceptions, these type names are" + + " not valid Starlark symbols; instances of them may be acquired through different" + + " means."), // Used for top-level modules of functions in the global namespace. Such modules will always // be usable solely by accessing their members, via modulename.funcname() or // modulename.constantname. // Examples: attr, cc_common, config, java_common - TOP_LEVEL_MODULE(null, null), + TOP_LEVEL_MODULE( + "Top-level Modules", + "toplevel", + "This section lists top-level modules. These symbols are available only in .bzl files."), CORE( "Core Starlark data types", + "core", "This section lists the data types of the Starlark" - + " core language."); + + " core language. With some exceptions, these type names are not valid Starlark" + + " symbols; instances of them may be acquired through different means."); // Maps (essentially free-form) strings in annotations to permitted categories. - static Category of(StarlarkBuiltin annot) { + public static Category of(StarlarkBuiltin annot) { switch (annot.category()) { case DocCategory.CONFIGURATION_FRAGMENT: return CONFIGURATION_FRAGMENT; @@ -283,12 +205,14 @@ static Category of(StarlarkBuiltin annot) { } } - private Category(String title, String description) { + Category(String title, String path, String description) { this.title = title; + this.path = path; this.description = description; } private final String title; + private final String path; private final String description; public String getTitle() { @@ -299,8 +223,8 @@ public String getDescription() { return description; } - public String getTemplateIdentifier() { - return name().toLowerCase().replace("_", "-"); + public String getPath() { + return path; } } } diff --git a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java index 38e9becd6f46b5..d7f99dae6ff566 100644 --- a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java +++ b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java @@ -15,8 +15,9 @@ import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; -import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc; +import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category; import com.google.devtools.build.docgen.starlark.StarlarkDocExpander; +import com.google.devtools.build.docgen.starlark.StarlarkDocPage; import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider; import com.google.devtools.build.lib.util.Classpath.ClassPathException; import com.google.devtools.build.skydoc.fakebuildapi.FakeStarlarkNativeModuleApi; @@ -33,7 +34,7 @@ */ public class SymbolFamilies { private final ImmutableList nativeRules; - private final ImmutableMap types; + private final ImmutableMap> allDocPages; // Mappings between Starlark names and Starlark entities generated from the fakebuildapi. private final ImmutableMap globals; @@ -51,7 +52,7 @@ public SymbolFamilies( expander.ruleExpander, configuredRuleClassProvider, inputDirs, denyList)); this.globals = Starlark.UNIVERSE; this.bzlGlobals = collectBzlGlobals(configuredRuleClassProvider); - this.types = StarlarkDocumentationCollector.getAllModules(expander); + this.allDocPages = StarlarkDocumentationCollector.getAllDocPages(expander); } /* @@ -78,8 +79,8 @@ public Map getBzlGlobals() { } // Returns a mapping between type names and module/type documentation. - public Map getTypes() { - return types; + public ImmutableMap> getAllDocPages() { + return allDocPages; } /* diff --git a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java index c941ad7a6f5833..d6f382f40ae519 100644 --- a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java +++ b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java @@ -29,22 +29,36 @@ public @interface GlobalMethods { /** The environment in which the global methods in the annotated class are available. */ enum Environment { - BUILD("BUILD files"), - WORKSPACE("WORKSPACE files"), - MODULE("MODULE.bazel files"), - BZL(".bzl files"), - ALL("All Starlark files"); + BUILD( + "BUILD files", + "This page contains global methods available in BUILD files. See also the Build" + + " Encyclopedia for extra functions and build rules," + + " which can also be used in BUILD files."), + WORKSPACE("WORKSPACE files", "This page contains global methods available in WORKSPACE files."), + MODULE( + "MODULE.bazel files", "This page contains global methods available in MODULE.bazel files."), + BZL(".bzl files", "This page contains global methods available in all .bzl files."), + ALL( + "All Starlark files", + "This page contains global methods available in all Starlark files, including BUILD," + + " WORKSPACE, MODULE.bazel, and all .bzl files."); private final String title; + private final String description; - Environment(String title) { + Environment(String title, String description) { this.title = title; + this.description = description; } public String getTitle() { return title; } + public String getDescription() { + return description; + } + public String getPath() { return Ascii.toLowerCase(name()); } diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java index 74a9738c4bf9f4..c83bf9bf2c51c8 100644 --- a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java +++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java @@ -1,4 +1,4 @@ -// Copyright 2014 The Bazel Authors. All rights reserved. +// Copyright 2023 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,155 +11,46 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. + package com.google.devtools.build.docgen.starlark; -import com.google.common.base.Preconditions; -import com.google.common.collect.HashMultimap; -import com.google.common.collect.ImmutableCollection; -import com.google.common.collect.ImmutableList; -import com.google.common.collect.ImmutableSortedSet; -import com.google.common.collect.Iterables; -import com.google.common.collect.Multimap; -import java.text.Collator; -import java.util.Collection; -import java.util.Comparator; -import java.util.Locale; -import java.util.TreeMap; -import javax.annotation.Nullable; import net.starlark.java.annot.StarlarkBuiltin; -import net.starlark.java.annot.StarlarkMethod; - -/** - * A class representing documentation for a Starlark built-in object with its {@link StarlarkModule} - * annotation and with the {@link StarlarkMethod} methods it documents. - */ -public final class StarlarkBuiltinDoc extends StarlarkDoc { - private final StarlarkBuiltin module; - private final String title; - private final Class classObject; - private final Multimap javaMethods; - private TreeMap methodMap; - @Nullable private StarlarkConstructorMethodDoc javaConstructor; - private final boolean isTopLevel; +/** A documentation page for a Starlark builtin type. */ +public final class StarlarkBuiltinDoc extends StarlarkDocPage { private static final String SOURCE_ROOT = "src/main/java"; - private static final String NO_SOURCE_FILE_VALUE = "NONE"; - public StarlarkBuiltinDoc( - StarlarkBuiltin module, String title, Class classObject, StarlarkDocExpander expander) { - this(module, title, classObject, expander, false); - } + private final StarlarkBuiltin starlarkBuiltin; + private final Class classObject; public StarlarkBuiltinDoc( - StarlarkBuiltin module, - String title, - Class classObject, - StarlarkDocExpander expander, - boolean isTopLevel) { + StarlarkBuiltin starlarkBuiltin, Class classObject, StarlarkDocExpander expander) { super(expander); - this.module = - Preconditions.checkNotNull( - module, "Class has to be annotated with StarlarkBuiltin: %s", classObject); - this.title = title; + this.starlarkBuiltin = starlarkBuiltin; this.classObject = classObject; - this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US)); - this.javaMethods = HashMultimap.create(); - this.isTopLevel = isTopLevel; } @Override public String getName() { - return module.name(); + return starlarkBuiltin.name(); } @Override public String getRawDocumentation() { - return module.doc(); + return starlarkBuiltin.doc(); } + @Override public String getTitle() { - return title; - } - - public StarlarkBuiltin getAnnotation() { - return module; + return starlarkBuiltin.name(); } public Class getClassObject() { return classObject; } - public void setConstructor(StarlarkConstructorMethodDoc method) { - Preconditions.checkState( - javaConstructor == null, - "Constructor method doc already set for %s:\n existing: %s\n attempted: %s", - getName(), - javaConstructor, - method); - javaConstructor = method; - } - - public void addMethod(StarlarkJavaMethodDoc method) { - if (!method.documented()) { - return; - } - - String shortName = method.getName(); - Collection overloads = javaMethods.get(shortName); - if (!overloads.isEmpty()) { - method.setOverloaded(true); - // Overload information only needs to be updated if we're discovering the first overload - // (= the second method of the same name). - if (overloads.size() == 1) { - Iterables.getOnlyElement(overloads).setOverloaded(true); - } - } - javaMethods.put(shortName, method); - - // If the method is overloaded, getName() now returns a longer, - // unique name including the names of the parameters. - StarlarkMethodDoc prev = methodMap.put(method.getName(), method); - if (prev != null && !prev.getMethod().equals(method.getMethod())) { - throw new IllegalStateException( - String.format( - "Starlark type '%s' (%s) has distinct overloads of %s: %s, %s", - module.name(), classObject, method.getName(), method.getMethod(), prev.getMethod())); - } - } - - public boolean javaMethodsNotCollected() { - return javaMethods.isEmpty(); - } - - public Collection getJavaMethods() { - ImmutableSortedSet.Builder methods = - new ImmutableSortedSet.Builder<>(Comparator.comparing(StarlarkMethodDoc::getName)); - - if (javaConstructor != null) { - methods.add(javaConstructor); - } - methods.addAll(javaMethods.values()); - return methods.build(); - } - - public ImmutableCollection getMethods() { - ImmutableList.Builder methods = ImmutableList.builder(); - if (javaConstructor != null) { - methods.add(javaConstructor); - } - return methods.addAll(methodMap.values()).build(); - } - - @Nullable - public StarlarkConstructorMethodDoc getConstructor() { - return javaConstructor; - } - + @Override public String getSourceFile() { - if (isTopLevel) { - return NO_SOURCE_FILE_VALUE; - } - String[] parts = classObject.getName().split("\\$", -1); return String.format("%s/%s.java", SOURCE_ROOT, parts[0].replace('.', '/')); } diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java index 582a0dad9fdab7..86e29f4ebcdef1 100644 --- a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java +++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDoc.java @@ -14,6 +14,7 @@ package com.google.devtools.build.docgen.starlark; import com.google.common.collect.ImmutableList; +import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category; import com.google.devtools.build.lib.collect.nestedset.NestedSet; import java.lang.reflect.Method; import java.util.Arrays; @@ -29,9 +30,7 @@ import net.starlark.java.eval.Tuple; /** Abstract class for containing documentation for a Starlark syntactic entity. */ -abstract class StarlarkDoc { - protected static final String TOP_LEVEL_ID = "globals"; - +public abstract class StarlarkDoc { private final StarlarkDocExpander expander; protected StarlarkDoc(StarlarkDocExpander expander) { @@ -63,28 +62,29 @@ protected String getTypeAnchor(Class returnType, Class generic1) { protected String getTypeAnchor(Class type) { if (type.equals(Boolean.class) || type.equals(boolean.class)) { - return "bool"; + return "bool"; } else if (type.equals(int.class) || type.equals(Integer.class)) { - return "int"; + return "int"; } else if (type.equals(String.class)) { - return "string"; + return "string"; } else if (Map.class.isAssignableFrom(type)) { - return "dict"; + return "dict"; } else if (type.equals(Tuple.class)) { - return "tuple"; + return "tuple"; } else if (type.equals(StarlarkList.class) || type.equals(ImmutableList.class)) { - return "list"; + return "list"; } else if (type.equals(Sequence.class)) { - return "sequence"; + return "sequence"; } else if (type.equals(Void.TYPE) || type.equals(NoneType.class)) { - return "None"; + return "None"; } else if (type.equals(NestedSet.class)) { - return "depset"; + return "depset"; } else if (StarlarkAnnotations.getStarlarkBuiltin(type) != null) { - StarlarkBuiltin module = StarlarkAnnotations.getStarlarkBuiltin(type); - if (module.documented()) { - return String.format("%1$s", - module.name()); + StarlarkBuiltin starlarkBuiltin = StarlarkAnnotations.getStarlarkBuiltin(type); + if (starlarkBuiltin.documented()) { + return String.format( + "%2$s", + Category.of(starlarkBuiltin).getPath(), starlarkBuiltin.name()); } } return Starlark.classType(type); diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java new file mode 100644 index 00000000000000..bb4a8757b94c30 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkDocPage.java @@ -0,0 +1,111 @@ +// Copyright 2023 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +package com.google.devtools.build.docgen.starlark; + +import com.google.common.base.Preconditions; +import com.google.common.collect.HashMultimap; +import com.google.common.collect.ImmutableCollection; +import com.google.common.collect.ImmutableList; +import com.google.common.collect.ImmutableSortedSet; +import com.google.common.collect.Iterables; +import com.google.common.collect.Multimap; +import java.text.Collator; +import java.util.Collection; +import java.util.Comparator; +import java.util.Locale; +import java.util.TreeMap; +import javax.annotation.Nullable; + +/** + * A typical Starlark documentation page, containing a bunch of field/method documentation entries. + */ +public abstract class StarlarkDocPage extends StarlarkDoc { + private final Multimap javaMethods; + private final TreeMap methodMap; + @Nullable private StarlarkConstructorMethodDoc javaConstructor; + + protected StarlarkDocPage(StarlarkDocExpander expander) { + super(expander); + this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US)); + this.javaMethods = HashMultimap.create(); + } + + public abstract String getTitle(); + + public void setConstructor(StarlarkConstructorMethodDoc method) { + Preconditions.checkState( + javaConstructor == null, + "Constructor method doc already set for %s:\n existing: %s\n attempted: %s", + getName(), + javaConstructor, + method); + javaConstructor = method; + } + + public void addMethod(StarlarkJavaMethodDoc method) { + if (!method.documented()) { + return; + } + + String shortName = method.getName(); + Collection overloads = javaMethods.get(shortName); + if (!overloads.isEmpty()) { + method.setOverloaded(true); + // Overload information only needs to be updated if we're discovering the first overload + // (= the second method of the same name). + if (overloads.size() == 1) { + Iterables.getOnlyElement(overloads).setOverloaded(true); + } + } + javaMethods.put(shortName, method); + + // If the method is overloaded, getName() now returns a longer, + // unique name including the names of the parameters. + StarlarkMethodDoc prev = methodMap.put(method.getName(), method); + if (prev != null && !prev.getMethod().equals(method.getMethod())) { + throw new IllegalStateException( + String.format( + "Starlark type '%s' has distinct overloads of %s: %s, %s", + getName(), method.getName(), method.getMethod(), prev.getMethod())); + } + } + + public Collection getJavaMethods() { + ImmutableSortedSet.Builder methods = + new ImmutableSortedSet.Builder<>(Comparator.comparing(StarlarkMethodDoc::getName)); + + if (javaConstructor != null) { + methods.add(javaConstructor); + } + methods.addAll(javaMethods.values()); + return methods.build(); + } + + public ImmutableCollection getMethods() { + ImmutableList.Builder methods = ImmutableList.builder(); + if (javaConstructor != null) { + methods.add(javaConstructor); + } + return methods.addAll(methodMap.values()).build(); + } + + @Nullable + public StarlarkConstructorMethodDoc getConstructor() { + return javaConstructor; + } + + /** Returns the path to the source file backing this doc page. */ + // This method may seem unused, but it's actually used in the template file (starlark-library.vm). + public abstract String getSourceFile(); +} diff --git a/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java new file mode 100644 index 00000000000000..1166af0d69e4ce --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/starlark/StarlarkGlobalsDoc.java @@ -0,0 +1,47 @@ +// Copyright 2023 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.devtools.build.docgen.starlark; + +import com.google.devtools.build.docgen.annot.GlobalMethods.Environment; + +/** A documentation page for a list of Starlark global methods in the same environment. */ +public final class StarlarkGlobalsDoc extends StarlarkDocPage { + private final Environment environment; + + public StarlarkGlobalsDoc(Environment environment, StarlarkDocExpander expander) { + super(expander); + this.environment = environment; + } + + @Override + public String getName() { + return environment.getPath(); + } + + @Override + public String getRawDocumentation() { + return environment.getDescription(); + } + + @Override + public String getTitle() { + return environment.getTitle(); + } + + @Override + public String getSourceFile() { + return "NONE"; + } +} diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html index 9eefe24bff2d17..8c448aa28e443c 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env.html @@ -17,7 +17,7 @@ Starlark-defined test rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a - TestEnvironment + TestEnvironment Provider.

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 fe0e48de3ab4b5..d05d3c7995f2d1 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 @@ -43,7 +43,7 @@
  • exports_files
  • glob
  • select
    • -
  • workspace
    • +
  • workspace

    • Rules

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm index 1ee5f68ff2524a..13a98279230ce6 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm +++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm @@ -11,9 +11,9 @@ ${description} diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm index 3e0b9774361402..efd62a3bbd000d 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm +++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm @@ -5,18 +5,18 @@ -

    ${module.title}

    +

    ${page.title}

    -{% dynamic setvar source_file "${module.sourceFile}" %} +{% dynamic setvar source_file "${page.sourceFile}" %} {% include "_buttons.html" %} -${module.documentation} +${page.documentation} -#if (!$module.methods.isEmpty()) +#if (!$page.methods.isEmpty())

    Members

      -#foreach ($method in $module.methods) +#foreach ($method in $page.methods) #if ($method.documented())
    • ${method.name} @@ -26,7 +26,7 @@ ${module.documentation}
    #end -#foreach ($method in $module.methods) +#foreach ($method in $page.methods) #if ($method.documented())

    ${method.name}

    #if (!$method.signature.isEmpty()) diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm deleted file mode 100644 index eb388295e90e7f..00000000000000 --- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-nav.vm +++ /dev/null @@ -1,5 +0,0 @@ -
  • Globals
    • -
  • Builtin Types and Modules
    • -
  • Configuration fragments
    • -
  • Providers
    • -
  • One-Page Overview
    • diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm index efdb298dd69574..6708e4f0b06cb5 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm +++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm @@ -8,84 +8,21 @@ {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm" %} {% include "_buttons.html" %} -A list of all modules and globals that are available: - -

    - - - Global Functions - - -

    -
      - -#foreach ($name in $global_functions) - -
    • - - - ${name} - - -
      • - -#end - -
    -

    - - - Global Constants - - -

    -
      - -#foreach ($name in $global_constants) - -
    • - - - ${name} - - -
      • - -#end - -
    -

    - Global Modules -

    -
      - -#foreach ($module in $global_modules) - -
    • - - - ${module.name} - -
      • - -#end - -
    -#foreach ($entry in $modules.entrySet()) +#foreach ($entry in $allPages.entrySet())

    - ${entry.key.title} + ${entry.key.title}

      -#foreach ($module in $entry.value) +#foreach ($page in $entry.value)
    • - ${module.title} + ${page.title}
      • diff --git a/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm b/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm index 2c8de9f18bb7cd..2358db08360a67 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm +++ b/src/main/java/com/google/devtools/build/docgen/templates/starlark-toc.vm @@ -2,23 +2,15 @@ toc: - title: Build API section: - title: Overview - path: /rules/lib/starlark-overview - - title: "Functions & Constants" - path: /rules/lib/globals - - title: Modules - section: -#foreach ($module in $global_modules) - - title: ${module.name} - path: /rules/lib/${module.name} -#end -#foreach ($entry in $modules.entrySet()) + path: /rules/lib/overview +#foreach ($entry in $allPages.entrySet()) - title: "${entry.key.title}" section: - title: Overview - path: /rules/lib/starlark-${entry.key.templateIdentifier} -#foreach ($module in $entry.value) - - title: ${module.title} - path: /rules/lib/${module.name} + path: /rules/lib/${entry.key.path} +#foreach ($page in $entry.value) + - title: ${page.title} + path: /rules/lib/${entry.key.path}/${page.name} #end #end - title: "Repository rules" diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD index 39c404de47a64e..1f7a2ffadb4739 100644 --- a/src/main/java/com/google/devtools/build/lib/BUILD +++ b/src/main/java/com/google/devtools/build/lib/BUILD @@ -551,7 +551,10 @@ genrule( " $(@D)/skylark-lib" + " --link_map_path=$(location //src/main/java/com/google/devtools/build/docgen:bazel_link_map)" + " --create_toc=true" + - " && zip -qj $@ $(@D)/skylark-lib/*", + " && OUTPUT=$$PWD/$@" + + " && pushd $(@D)/skylark-lib" + + " && zip -qr $$OUTPUT ." + + " && popd", tools = ["//src/main/java/com/google/devtools/build/docgen:skydoc_bin"], visibility = ["//site:__pkg__"], ) diff --git a/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java index 2e95ec50b10990..84f91134adc2ea 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java @@ -34,7 +34,6 @@ import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableSet; -import com.google.devtools.build.lib.actions.Artifact; import com.google.devtools.build.lib.analysis.Allowlist; import com.google.devtools.build.lib.analysis.BaseRuleClasses; import com.google.devtools.build.lib.analysis.RuleDefinitionEnvironment; @@ -117,7 +116,7 @@ import net.starlark.java.syntax.Location; /** A helper class to provide an easier API for Starlark rule definitions. */ -public class StarlarkRuleClassFunctions implements StarlarkRuleFunctionsApi { +public class StarlarkRuleClassFunctions implements StarlarkRuleFunctionsApi { // A cache for base rule classes (especially tests). private static final LoadingCache labelCache = Caffeine.newBuilder().build(Label::parseCanonical); diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java index 0cf2fd58a9a15d..90d1f9b7f34705 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtensionContext.java @@ -95,9 +95,10 @@ protected ImmutableMap getRemoteExecProperties() throws EvalExce structField = true, doc = "A list of all the Bazel modules in the external dependency graph, each of which is a bazel_module object that exposes all the tags it" - + " specified for this module extension. The iteration order of this dictionary is" - + " guaranteed to be the same as breadth-first search starting from the root module.") + + " href=\"../builtins/bazel_module.html\">bazel_module object that exposes all" + + " the tags it specified for this module extension. The iteration order of this" + + " dictionary is guaranteed to be the same as breadth-first search starting from the" + + " root module.") public StarlarkList getModules() { return modules; } @@ -106,12 +107,14 @@ public StarlarkList getModules() { name = "is_dev_dependency", doc = "Returns whether the given tag was specified on the result of a use_extension call with " + + "href=\"../globals/module.html#use_extension\">use_extension call with " + "devDependency = True.", parameters = { @Param( name = "tag", - doc = "A tag obtained from bazel_module.tags.", + doc = + "A tag obtained from bazel_module.tags.", allowedTypes = {@ParamType(type = TypeCheckedTag.class)}) }) public boolean isDevDependency(TypeCheckedTag tag) { diff --git a/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java b/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java index 803198841453db..ef4e6111f095a0 100644 --- a/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java +++ b/src/main/java/com/google/devtools/build/lib/collect/nestedset/Depset.java @@ -63,8 +63,8 @@ + " If you need a general set datatype, you can" + " simulate one using a dictionary where all keys map to True." + "

      Depsets are immutable. They should be created using their constructor function and merged or augmented with" - + " other depsets via the transitive argument. " + + " href=\"../globals/bzl.html#depset\">constructor function and merged or" + + " augmented with other depsets via the transitive argument. " + "

      The order parameter determines the" + " kind of traversal that is done to convert the depset to an iterable. There are" + " four possible values:" diff --git a/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java b/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java index b9922d965fd644..085d3bf1571e67 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java +++ b/src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java @@ -76,8 +76,8 @@ private static ImmutableMap initCommon() { /** Proto defines the "proto" Starlark module of utilities for protocol message processing. */ @StarlarkBuiltin( - name = "ProtoModule", // not "proto", to avoid conflict with ctx.fragments.proto data type - category = DocCategory.BUILTIN, + name = "proto", + category = DocCategory.TOP_LEVEL_MODULE, doc = "A module for protocol message processing.") static final class Proto implements StarlarkValue { @@ -266,11 +266,12 @@ private static final class DepsetLibrary { @StarlarkMethod( name = "depset", doc = - "Creates a depset. The direct parameter is a" - + " list of direct elements of the depset, and transitive parameter is" - + " a list of depsets whose elements become indirect elements of the created" - + " depset. The order in which elements are returned when the depset is converted" - + " to a list is specified by the order parameter. See the depset. The direct" + + " parameter is a list of direct elements of the depset, and" + + " transitive parameter is a list of depsets whose elements become" + + " indirect elements of the created depset. The order in which elements are" + + " returned when the depset is converted to a list is specified by the" + + " order parameter. See the Depsets overview for more" + " information.\n" // + "

      All" @@ -312,7 +313,7 @@ private static final class DepsetLibrary { defaultValue = "\"default\"", doc = "The traversal strategy for the new depset. See " - + "here for the possible values.", + + "here for the possible values.", named = true), @Param( name = "transitive", @@ -349,7 +350,7 @@ public static final class SelectLibrary { positional = true, doc = "A dict that maps configuration conditions to values. Each key is a " - + "Label or a label string" + + "Label or a label string" + " that identifies a config_setting or constraint_value instance. See the" + " " + "documentation on macros for when to use a Label instead of a string."), diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java index fadb27c67ba1c3..af8f20965c578c 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/ActionApi.java @@ -33,14 +33,14 @@ category = DocCategory.BUILTIN, doc = "An action created during rule analysis.

      This object is visible for the purpose of" - + " testing, and may be obtained from an Actions" - + " provider. It is normally not necessary to access Action objects or" - + " their fields within a rule's implementation function. You may instead want to see" - + " the Rules page for a" - + " general discussion of how to use actions when defining custom rules, or the API reference for creating actions.

      Some fields of this" - + " object are only applicable for certain kinds of actions. Fields that are" - + " inapplicable are set to None.") + + " testing, and may be obtained from an Actions provider. It is normally" + + " not necessary to access Action objects or their fields within a rule's" + + " implementation function. You may instead want to see the Rules page for a general" + + " discussion of how to use actions when defining custom rules, or the API reference for creating actions.

      Some" + + " fields of this object are only applicable for certain kinds of actions. Fields that" + + " are inapplicable are set to None.") public interface ActionApi extends StarlarkValue { @StarlarkMethod(name = "mnemonic", structField = true, doc = "The mnemonic for this action.") @@ -61,11 +61,11 @@ public interface ActionApi extends StarlarkValue { @StarlarkMethod( name = "argv", doc = - "For actions created by ctx.actions.run() " - + "or ctx.actions.run_shell() an immutable " - + "list of the arguments for the command line to be executed. Note that " - + "for shell actions the first two arguments will be the shell path " - + "and \"-c\".", + "For actions created by ctx.actions.run() or" + + " ctx.actions.run_shell() an" + + " immutable list of the arguments for the command line to be executed. Note that" + + " for shell actions the first two arguments will be the shell path and" + + " \"-c\".", structField = true, allowReturnNones = true) @Nullable @@ -74,14 +74,14 @@ public interface ActionApi extends StarlarkValue { @StarlarkMethod( name = "args", doc = - "A list of frozen Args objects containing information about" - + " the action arguments. These objects contain accurate argument information," - + " including arguments involving expanded action output directories. However, Args objects are not readable in the analysis phase. For" - + " a less accurate account of arguments which is available in the analysis phase," - + " see argv." - + "

      Note that some types of actions do not yet support exposure of this field." - + " For such action types, this is None.", + "A list of frozen Args objects containing" + + " information about the action arguments. These objects contain accurate argument" + + " information, including arguments involving expanded action output directories." + + " However, Args objects are not readable in" + + " the analysis phase. For a less accurate account of arguments which is available" + + " in the analysis phase, see argv.

      Note that some types of" + + " actions do not yet support exposure of this field. For such action types, this is" + + " None.", structField = true, allowReturnNones = true) @Nullable @@ -101,12 +101,13 @@ public interface ActionApi extends StarlarkValue { @StarlarkMethod( name = "content", doc = - "For actions created by ctx.actions.write() or " - + "ctx.actions.expand_template()," + "For actions created by ctx.actions.write() or ctx.actions.expand_template()," + " the contents of the file to be written, if those contents can be computed during " - + " the analysis phase. The value is None if the contents cannot be " - + "determined until the execution phase, such as when a directory in an " - + "Args object needs to be expanded.", + + " the analysis phase. The value is None if the contents cannot be" + + " determined until the execution phase, such as when a directory in an Args object needs to be expanded.", structField = true, allowReturnNones = true) @Nullable @@ -115,8 +116,8 @@ public interface ActionApi extends StarlarkValue { @StarlarkMethod( name = "substitutions", doc = - "For actions created by " - + "ctx.actions.expand_template()," + "For actions created by ctx.actions.expand_template()," + " an immutable dict holding the substitution mapping.", structField = true, allowReturnNones = true) diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java index b6b762c6f2549d..2a2f2d06b0ac82 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/BuildConfigurationApi.java @@ -71,7 +71,7 @@ public interface BuildConfigurationApi extends StarlarkValue { "A boolean that tells whether code coverage is enabled for this run. Note that this does" + " not compute whether a specific rule should be instrumented for code coverage data" + " collection. For that, see the ctx.coverage_instrumented" + + " href=\"../builtins/ctx.html#coverage_instrumented\">ctx.coverage_instrumented" + " function.") boolean isCodeCoverageEnabled(); diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java index 75c71262018606..e5272bd39eeb04 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/CommandLineArgsApi.java @@ -34,15 +34,15 @@ doc = "An object that encapsulates, in a memory-efficient way, the data needed to build part or " + "all of a command line." - + "" - + "

      It often happens that an action requires a large command line containing values " - + "accumulated from transitive dependencies. For example, a linker command line might " - + "list every object file needed by all of the libraries being linked. It is best " - + "practice to store such transitive data in depset" - + "s, so that they can be shared by multiple targets. However, if the rule " - + "author had to convert these depsets into lists of strings in order to construct an " - + "action command line, it would defeat this memory-sharing optimization." - + "" + + "" // + + "

      It often happens that an action requires a large command line containing values" + + " accumulated from transitive dependencies. For example, a linker command line might" + + " list every object file needed by all of the libraries being linked. It is best" + + " practice to store such transitive data in depsets, so that they can be shared" + + " by multiple targets. However, if the rule author had to convert these depsets into" + + " lists of strings in order to construct an action command line, it would defeat this" + + " memory-sharing optimization." // + "

      For this reason, the action-constructing functions accept Args " + "objects in addition to strings. Each Args object represents a " + "concatenation of strings and depsets, with optional transformations for " @@ -51,27 +51,27 @@ + "line. This helps defer any expensive copying until after the analysis phase is " + "complete. See the Optimizing " + "Performance page for more information." - + "" - + "

      Args are constructed by calling " - + "ctx.actions.args(). They can be passed as the arguments " - + "parameter of ctx.actions.run() or " - + "ctx.actions.run_shell(). Each " - + "mutation of an Args object appends values to the eventual command " - + "line." - + "" + + "" // + + "

      Args are constructed by calling ctx.actions.args(). They can" + + " be passed as the arguments parameter of ctx.actions.run() or ctx.actions.run_shell()." + + " Each mutation of an Args object appends values to the eventual command" + + " line." // + "

      The map_each feature allows you to customize how items are " + "transformed into strings. If you do not provide a map_each function, " + "the standard conversion is as follows: " - + "

        " - + "
      • Values that are already strings are left as-is." - + "
      • File objects are turned into their " - + " File.path values." + + "
          " // + + "
        • Values that are already strings are left as-is." // + + "
        • File objects are turned into" + + " their File.path values." // + "
        • All other types are turned into strings in an unspecified manner. For " + " this reason, you should avoid passing values that are not of string or " + " File type to add(), and if you pass them to " + " add_all() or add_joined() then you should provide a " + " map_each function." - + "
        " + + "
      " // + "" + "

      When using string formatting (format, format_each, and " + "format_joined params of the add*() methods), the format " @@ -79,7 +79,7 @@ + "except that the template must have exactly one substitution placeholder and it must " + "be %s. Literal percents may be escaped as %%. Formatting " + "is applied after the value is converted to a string as per the above." - + "" + + "" // + "

      Each of the add*() methods have an alternate form that accepts an " + "extra positional parameter, an \"arg name\" string to insert before the rest of the " + "arguments. For add_all and add_joined the extra string " @@ -87,12 +87,12 @@ + "For instance, the same usage can add either --foo val1 val2 val3 --bar" + " or just --bar to the command line, depending on whether the " + "given sequence contains val1..val3 or is empty." - + "" + + "" // + "

      If the size of the command line can grow longer than the maximum size allowed by " + "the system, the arguments can be spilled over into parameter files. See " + "use_param_file() and " + "set_param_file_format()." - + "" + + "" // + "

      Example: Suppose we wanted to generate the command line: " + "

      \n"
             + "--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz\n"
@@ -211,45 +211,35 @@ CommandLineArgsApi addArgument(
             positional = false,
             defaultValue = "None",
             doc =
-                "A function that converts each item to zero or more strings, which may be further "
-                    + "processed before appending. If this param is not provided, the standard "
-                    + "conversion is used."
-                    + ""
-                    + "
      The function is passed either one or two positional arguments: the item "
-                    + "to convert, followed by an optional "
-                    + "DirectoryExpander"
-                    + ". The second argument will be passed only if the supplied "
-                    + "function is user-defined (not built-in) and declares more than one "
-                    + "parameter."
-                    + "
      The return value's type depends on how many arguments are to be produced "
-                    + "for the item:"
-                    + "
        "
-                    + "
      • In the common case when each item turns into one string, the function "
-                    + "    should return that string."
-                    + "
      • If the item is to be filtered out entirely, the function should return "
-                    + "    None."
-                    + "
      • If the item turns into multiple strings, the function returns a list of "
-                    + "    those strings."
-                    + "
      "
-                    + "Returning a single string or None has the same effect as "
-                    + "returning a list of length 1 or length 0 respectively. However, it is more "
-                    + "efficient and readable to avoid creating a list where it is not needed."
-                    + ""
-                    + "
      Ordinarily, items that are directories are automatically expanded to "
-                    + "their contents when expand_directories=True is set. However, "
-                    + "this will not expand directories contained inside other values -- for "
-                    + "instance, when the items are structs that have directories as fields. In "
-                    + "this situation, the DirectoryExpander argument can be applied "
-                    + "to manually obtain the files of a given directory."
-                    + ""
-                    + "
      To avoid unintended retention of large analysis-phase data structures "
-                    + "into the execution phase, the map_each function must be "
-                    + "declared by a top-level def statement; it may not be a "
-                    + "nested function closure by default."
-                    + ""
-                    + "
      Warning: print() "
-                    + "statements that are executed during the call to map_each will "
-                    + "not produce any visible output."),
+                "A function that converts each item to zero or more strings, which may be further"
+                    + " processed before appending. If this param is not provided, the standard"
+                    + " conversion is used.
      The function is passed either one or two positional"
+                    + " arguments: the item to convert, followed by an optional DirectoryExpander"
+                    + ". The second argument will be passed only if the supplied function is"
+                    + " user-defined (not built-in) and declares more than one parameter.
      The"
+                    + " return value's type depends on how many arguments are to be produced for"
+                    + " the item:
      • In the common case when each item turns into one string,"
+                    + " the function     should return that string.
      • If the item is to be"
+                    + " filtered out entirely, the function should return    "
+                    + " None.
      • If the item turns into multiple strings, the function"
+                    + " returns a list of     those strings.
      Returning a single string or"
+                    + " None has the same effect as returning a list of length 1 or"
+                    + " length 0 respectively. However, it is more efficient and readable to avoid"
+                    + " creating a list where it is not needed.
      Ordinarily, items that are"
+                    + " directories are automatically expanded to their contents when"
+                    + " expand_directories=True is set. However, this will not expand"
+                    + " directories contained inside other values -- for instance, when the items"
+                    + " are structs that have directories as fields. In this situation, the"
+                    + " DirectoryExpander argument can be applied to manually obtain"
+                    + " the files of a given directory.
      To avoid unintended retention of large"
+                    + " analysis-phase data structures into the execution phase, the"
+                    + " map_each function must be declared by a top-level"
+                    + " def statement; it may not be a nested function closure by"
+                    + " default.
      Warning: print() statements that"
+                    + " are executed during the call to map_each will not produce any"
+                    + " visible output."),
         @Param(
             name = "format_each",
             allowedTypes = {
@@ -389,7 +379,7 @@ CommandLineArgsApi addAll(
             doc =
                 "A delimiter string used to join together the strings obtained from applying "
                     + "map_each and format_each, in the same manner as "
-                    + "string.join()."),
+                    + "string.join()."),
         @Param(
             name = "map_each",
             allowedTypes = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java
index 6a26bdf73aaa9c..bd90d5d83e694a 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DefaultInfoApi.java
@@ -50,10 +50,10 @@ public interface DefaultInfoApi extends StructApi {
   @StarlarkMethod(
       name = "files",
       doc =
-          "A depset of "
-              + "File objects representing the default "
-              + "outputs to build when this target is specified on the bazel command line. By "
-              + "default it is all predeclared outputs.",
+          "A depset of File objects representing the"
+              + " default outputs to build when this target is specified on the bazel command line."
+              + " By default it is all predeclared outputs.",
       structField = true,
       allowReturnNones = true)
   @Nullable
@@ -62,8 +62,8 @@ public interface DefaultInfoApi extends StructApi {
   @StarlarkMethod(
       name = "files_to_run",
       doc =
-          "A FilesToRunProvider object "
-              + "containing information about the executable and runfiles of the target.",
+          "A FilesToRunProvider"
+              + " object containing information about the executable and runfiles of the target.",
       structField = true,
       allowReturnNones = true)
   @Nullable
@@ -111,10 +111,10 @@ interface DefaultInfoApiProviderdepset of File objects representing the default"
-                      + " outputs to build when this target is specified on the bazel command"
-                      + " line. By default it is all predeclared outputs."),
+                  "A depset of File objects representing"
+                      + " the default outputs to build when this target is specified on the bazel"
+                      + " command line. By default it is all predeclared outputs."),
           @Param(
               name = "runfiles",
               allowedTypes = {
@@ -165,11 +165,11 @@ interface DefaultInfoApiProviderexecutable or test, this is a File object representing the file that"
-                      + " should be executed to run the target. By default it is the predeclared"
-                      + " output ctx.outputs.executable.")
+                      + " href='../globals/bzl.html#rule.executable'>executable or"
+                      + " test, this is a"
+                      + " File object representing"
+                      + " the file that should be executed to run the target. By default it is the"
+                      + " predeclared output ctx.outputs.executable.")
         },
         selfCall = true,
         useStarlarkThread = true)
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java
index 3cd8d9cf772767..63f42ab710f6d3 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/DirectoryExpander.java
@@ -26,10 +26,10 @@
     name = "DirectoryExpander",
     category = DocCategory.BUILTIN,
     doc =
-        "Expands directories created by "
+        "Expands directories created by "
             + "ctx.actions.declare_directory"
             + " during the execution phase. This is useful to expand directories in "
-            + "map_each.")
+            + "map_each.")
 public interface DirectoryExpander extends StarlarkValue {
   @StarlarkMethod(
       name = "expand",
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java
index ef1b59d3a57dd5..a3b444c93c900f 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FileApi.java
@@ -37,7 +37,7 @@
             + "information."
             + "" // curse google-java-format b/145078219
             + "
      When a File is passed to an Args object without using a"
+            + " href='../builtins/Args.html'>Args object without using a"
             + " map_each function, it is converted to a string by taking the value of"
             + " its path field.")
 public interface FileApi extends StarlarkValue {
@@ -103,25 +103,26 @@ public interface FileApi extends StarlarkValue {
       name = "path",
       structField = true,
       doc =
-          "The execution path of this file, relative to the workspace's execution directory. It "
-              + "consists of two parts, an optional first part called the root (see also "
-              + "the root module), and the second part which is the "
-              + "short_path. The root may be empty, which it usually is for "
-              + "non-generated files. For generated files it usually contains a "
-              + "configuration-specific path fragment that encodes things like the target CPU "
-              + "architecture that was used while building said file. Use the "
-              + "short_path for the path under which the file is mapped if it's in "
-              + "the runfiles of a binary.")
+          "The execution path of this file, relative to the workspace's execution directory. It"
+              + " consists of two parts, an optional first part called the root (see also"
+              + " the root module), and the second part which"
+              + " is the short_path. The root may be empty, which it usually is for"
+              + " non-generated files. For generated files it usually contains a"
+              + " configuration-specific path fragment that encodes things like the target CPU"
+              + " architecture that was used while building said file. Use the"
+              + " short_path for the path under which the file is mapped if it's in"
+              + " the runfiles of a binary.")
   String getExecPathString();
 
   @StarlarkMethod(
       name = "tree_relative_path",
       structField = true,
       doc =
-          "The path of this file relative to the root of the ancestor's tree, if the ancestor's "
-              + "is_directory field is true. tree_relative_path"
-              + " is only available for expanded files of a directory in an action command, "
-              + "i.e. Args.add_all(). For other types of files, "
-              + "it is an error to access this field.")
+          "The path of this file relative to the root of the ancestor's tree, if the ancestor's is_directory field is true."
+              + " tree_relative_path is only available for expanded files of a"
+              + " directory in an action command, i.e. Args.add_all(). For other types of"
+              + " files, it is an error to access this field.")
   String getTreeRelativePathString() throws EvalException;
 }
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java
index d7b9a85c9c485c..1cc123cbcd2995 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/FragmentCollectionApi.java
@@ -28,7 +28,7 @@
             + " context. Access a specific fragment by its field name. For example,"
             + " ctx.fragments.java 
      Only configuration fragments which are declared"
             + " in the rule definition may be accessed in this collection.
      See the configuration"
+            + " href=\"../fragments\">configuration"
             + " fragment reference for a list of available fragments and the rules"
             + " documentation for how to use them.")
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java
index 96643233379119..52a0b90e07d9df 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/LateBoundDefaultApi.java
@@ -28,6 +28,6 @@
             + " function, and depends on the current build configuration. For example, a"
             + " LateBoundDefault might represent the Label of the java toolchain in the current"
             + " build configuration. 
      See configuration_field for example"
-            + " usage.")
+            + " href=\"../globals/bzl.html#configuration_field\">configuration_field for"
+            + " example usage.")
 public interface LateBoundDefaultApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java
index ab4da2b27ae943..72fa2fa3e25851 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/RunfilesApi.java
@@ -31,11 +31,11 @@
     category = DocCategory.BUILTIN,
     doc =
         "A container of information regarding a set of files required at runtime execution. This"
-            + " object should be passed via DefaultInfo in order"
-            + " to tell the build system about the runfiles needed by the outputs produced by the"
-            + " rule. 
      See runfiles"
-            + " guide for details.")
+            + " object should be passed via DefaultInfo in order to tell the build"
+            + " system about the runfiles needed by the outputs produced by the rule. 
      See runfiles guide for"
+            + " details.")
 public interface RunfilesApi extends StarlarkValue {
 
   @StarlarkMethod(name = "files", doc = "Returns the set of runfiles as files.", structField = true)
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java
index c09773d9310318..fdd8b466ab90a7 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java
@@ -35,8 +35,8 @@
     name = "actions",
     category = DocCategory.BUILTIN,
     doc =
-        "Module providing functions to create actions. "
-            + "Access this module using ctx.actions.")
+        "Module providing functions to create actions. Access this module using ctx.actions.")
 public interface StarlarkActionFactoryApi extends StarlarkValue {
 
   @StarlarkMethod(
@@ -52,7 +52,7 @@ public interface StarlarkActionFactoryApi extends StarlarkValue {
               + " href='https://bazel.build/extending/rules#files'>predeclared output files do"
               + " not need to be (and cannot be) declared using this function. You can obtain their"
               + " File objects from ctx.outputs instead. ctx.outputs instead. See"
               + " example of use.",
       parameters = {
@@ -84,7 +84,7 @@ public interface StarlarkActionFactoryApi extends StarlarkValue {
               + "current package. You must create an action that generates the directory. "
               + "The contents of the directory are not directly accessible from Starlark, "
               + "but can be expanded in an action command with "
-              + "Args.add_all(). "
+              + "Args.add_all(). "
               + "Only regular files and directories can be in the expanded contents of a "
               + "declare_directory.",
       parameters = {
@@ -257,9 +257,9 @@ void symlink(
               @ParamType(type = CommandLineArgsApi.class)
             },
             doc =
-                "the contents of the file. "
-                    + "May be a either a string or an "
-                    + "actions.args() object.",
+                "the contents of the file. May be a either a string or an actions.args()"
+                    + " object.",
             named = true),
         @Param(
             name = "is_executable",
@@ -349,7 +349,7 @@ void symlink(
             doc =
                 "Command line arguments of the action. "
                     + "Must be a list of strings or "
-                    + "actions.args() objects."),
+                    + "actions.args() objects."),
         @Param(
             name = "mnemonic",
             allowedTypes = {
@@ -551,7 +551,7 @@ void run(
             positional = false,
             doc =
                 "Command line arguments of the action. Must be a list of strings or "
-                    + "actions.args() objects."
+                    + "actions.args() objects."
                     + ""
                     + "
      Bazel passes the elements in this attribute as arguments to the command."
                     + "The command can access these arguments using shell variable substitutions "
@@ -590,7 +590,7 @@ void run(
                     + "elements in arguments are made available to the command as "
                     + "$1, $2 (or %1, %2 if "
                     + "using Windows batch), etc. If arguments contains "
-                    + "any actions.args() objects, "
+                    + "any actions.args() objects, "
                     + "their contents are appended one by one to the command line, so "
                     + "$i can refer to individual strings within an Args "
                     + "object. Note that if an Args object of unknown size is passed as part of "
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java
index 6c1744d6110c69..7d7853f47131f6 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAspectApi.java
@@ -23,7 +23,7 @@
     name = "Aspect",
     category = DocCategory.BUILTIN,
     doc =
-        "For more information about Aspects, please consult the "
-            + "documentation of the aspect function or the "
-            + "introduction to Aspects.")
+        "For more information about Aspects, please consult the documentation of the aspect function or the"
+            + " introduction to Aspects.")
 public interface StarlarkAspectApi extends StarlarkValue {}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java
index 865211675ca980..cc1721dc1a96ea 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkAttrModuleApi.java
@@ -43,34 +43,35 @@
         "This is a top-level module for defining the attribute schemas of a rule or aspect. Each"
             + " function returns an object representing the schema of a single attribute. These"
             + " objects are used as the values of the attrs dictionary argument of rule() and aspect().
      See the Rules page for"
-            + " more on defining and"
-            + " using"
+            + " href=\"../globals/bzl.html#rule\">rule() and aspect().
      See the Rules page"
+            + " for more on defining"
+            + " and using"
             + " attributes.")
 public interface StarlarkAttrModuleApi extends StarlarkValue {
 
   // dependency and output attributes
   String LABEL_PARAGRAPH =
-      "
      This attribute contains unique Label values. If a "
-          + "string is supplied in place of a Label, it will be converted using the "
-          + "label constructor. The relative parts of the label "
-          + "path, including the (possibly renamed) repository, are resolved with respect to the "
-          + "instantiated target's package.";
+      "
      This attribute contains unique Label"
+          + " values. If a string is supplied in place of a Label, it will be"
+          + " converted using the label constructor. The"
+          + " relative parts of the label path, including the (possibly renamed) repository, are"
+          + " resolved with respect to the instantiated target's package.";
 
   // attr.label, attr.label_list, attr.label_keyed_string_dict
   String DEPENDENCY_ATTR_TEXT =
       LABEL_PARAGRAPH
-          + "
      At analysis time (within the rule's implementation function), when retrieving the "
-          + "attribute value from ctx.attr, labels are replaced by the corresponding "
-          + "Targets. This allows you to access the "
-          + "providers of the current target's dependencies.";
+          + "
      At analysis time (within the rule's implementation function), when retrieving the"
+          + " attribute value from ctx.attr, labels are replaced by the corresponding"
+          + " Targets. This allows you to access"
+          + " the providers of the current target's dependencies.";
 
   // attr.output, attr.output_list
   String OUTPUT_ATTR_TEXT =
       LABEL_PARAGRAPH
-          + "
      At analysis time, the corresponding File can "
-          + "be retrieved using ctx.outputs.";
+          + "
      At analysis time, the corresponding File can be retrieved using ctx.outputs.";
 
   String ALLOW_FILES_ARG = "allow_files";
   String ALLOW_FILES_DOC =
@@ -127,17 +128,15 @@ public interface StarlarkAttrModuleApi extends StarlarkValue {
 
   String PROVIDERS_ARG = "providers";
   String PROVIDERS_DOC =
-      "The providers that must be given by any dependency appearing in this attribute."
-          + ""
-          + "
      The format of this argument is a list of lists of providers -- *Info "
-          + "objects returned by provider() (or "
-          + "in the case of a legacy provider, its string name). The dependency must return ALL "
-          + "providers mentioned in at least ONE of the inner lists. As a convenience, this "
-          + "argument may also be a single-level list of providers, in which case it is wrapped in "
-          + "an outer list with one element."
-          + ""
-          + "It is NOT required that the rule of the dependency advertises those providers "
-          + "in its provides parameter, however, it is considered best practice.";
+      "The providers that must be given by any dependency appearing in this attribute.
      The format"
+          + " of this argument is a list of lists of providers -- *Info objects"
+          + " returned by provider() (or in"
+          + " the case of a legacy provider, its string name). The dependency must return ALL"
+          + " providers mentioned in at least ONE of the inner lists. As a convenience, this"
+          + " argument may also be a single-level list of providers, in which case it is wrapped in"
+          + " an outer list with one element.It is NOT required that the rule of the dependency"
+          + " advertises those providers in its provides parameter, however, it is"
+          + " considered best practice.";
 
   String ALLOW_SINGLE_FILE_ARG = "allow_single_file";
 
@@ -149,10 +148,9 @@ public interface StarlarkAttrModuleApi extends StarlarkValue {
   @StarlarkMethod(
       name = "int",
       doc =
-          "Creates a schema for an integer attribute. The value must be in the signed 32-bit"
-              + " range. The corresponding "
-              + "ctx.attr attribute will be of "
-              + "type int.",
+          "Creates a schema for an integer attribute. The value must be in the signed 32-bit range."
+              + " The corresponding ctx.attr"
+              + " attribute will be of type int.",
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -192,7 +190,7 @@ Descriptor intAttribute(
 
   @StarlarkMethod(
       name = "string",
-      doc = "Creates a schema for a string attribute.",
+      doc = "Creates a schema for a string attribute.",
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -268,9 +266,10 @@ Descriptor stringAttribute(
             positional = false,
             doc =
                 DEFAULT_DOC
-                    + "Use a string or the Label "
-                    + "function to specify a default value, for example, "
-                    + "attr.label(default = \"//a:b\")."),
+                    + "Use a string or the Label function to"
+                    + " specify a default value, for example, attr.label(default ="
+                    + " \"//a:b\")."),
         @Param(
             name = DOC_ARG,
             allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
@@ -302,7 +301,7 @@ Descriptor stringAttribute(
             positional = false,
             doc =
                 "This is similar to allow_files, with the restriction that the label "
-                    + "must correspond to a single File. "
+                    + "must correspond to a single File. "
                     + "Access it through ctx.file.<attribute_name>."),
         @Param(
             name = MANDATORY_ARG,
@@ -435,9 +434,9 @@ Descriptor intListAttribute(
       name = "label_list",
       doc =
           "
      Creates a schema for a list-of-labels attribute. This is a dependency attribute. "
-              + "The corresponding ctx.attr "
-              + "attribute will be of type list of "
-              + "Targets.
      "
+              + "The corresponding ctx.attr "
+              + "attribute will be of type list of "
+              + "Targets.
      "
               + DEPENDENCY_ATTR_TEXT,
       parameters = {
         @Param(name = ALLOW_EMPTY_ARG, defaultValue = "True", doc = ALLOW_EMPTY_DOC, named = true),
@@ -452,9 +451,10 @@ Descriptor intListAttribute(
             positional = false,
             doc =
                 DEFAULT_DOC
-                    + "Use strings or the Label "
-                    + "function to specify default values, for example, "
-                    + "attr.label_list(default = [\"//a:b\", \"//a:c\"])."),
+                    + "Use strings or the Label function to"
+                    + " specify default values, for example, attr.label_list(default ="
+                    + " [\"//a:b\", \"//a:c\"])."),
         @Param(
             name = DOC_ARG,
             allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
@@ -550,10 +550,11 @@ Descriptor labelListAttribute(
             positional = false,
             doc =
                 DEFAULT_DOC
-                    + "Use strings or the Label "
-                    + "function to specify default values, for example, "
-                    + "attr.label_keyed_string_dict(default = "
-                    + "{\"//a:b\": \"value\", \"//a:c\": \"string\"})."),
+                    + "Use strings or the Label function to"
+                    + " specify default values, for example,"
+                    + " attr.label_keyed_string_dict(default = {\"//a:b\": \"value\","
+                    + " \"//a:c\": \"string\"})."),
         @Param(
             name = DOC_ARG,
             allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
@@ -634,8 +635,8 @@ Descriptor labelKeyedStringDictAttribute(
       name = "bool",
       doc =
           "Creates a schema for a boolean attribute. The corresponding ctx.attr attribute will be of type"
-              + " bool.",
+              + " href='../builtins/ctx.html#attr'>ctx.attr attribute will be of"
+              + " type bool.",
       parameters = {
         @Param(
             name = DEFAULT_ARG,
@@ -829,9 +830,9 @@ Descriptor licenseAttribute(
       name = "Attribute",
       category = DocCategory.BUILTIN,
       doc =
-          "Representation of a definition of an attribute. Use the attr "
-              + "module to create an Attribute. They are only for use with a "
-              + "rule or an "
-              + "aspect.")
+          "Representation of a definition of an attribute. Use the attr module to create an Attribute. They are"
+              + " only for use with a rule or an aspect.")
   interface Descriptor extends StarlarkValue {}
 }
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java
index c05ff28bb9f27f..5116a57e2893d5 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java
@@ -89,14 +89,14 @@ public interface StarlarkBuildApiGlobals {
       // TODO(cparsons): Provide a link to documentation for available StarlarkConfigurationFields.
       doc =
           "References a late-bound default value for an attribute of type label. A value is 'late-bound' if it requires the"
-              + " configuration to be built before determining the value. Any attribute using this"
-              + " as a value must"
-              + " be"
-              + " private. 
      Example usage: 
      Defining a rule attribute: 
      label. A value is 'late-bound' if it"
+              + " requires the configuration to be built before determining the value. Any"
+              + " attribute using this as a value must be private."
+              + " 
      Example usage: 
      Defining a rule attribute: 
      '_foo':"
-              + " attr.label(default=configuration_field(fragment='java', "
-              + "name='toolchain'))

      Accessing in rule implementation:

      Accessing in rule implementation:
      def _rule_impl(ctx):\n" + " foo_info = ctx.attr._foo\n" + " ...", diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java index 66770ad58fb6c8..a7527847f6cb82 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java @@ -15,6 +15,8 @@ package com.google.devtools.build.lib.starlarkbuildapi; import com.google.devtools.build.docgen.annot.DocCategory; +import com.google.devtools.build.docgen.annot.GlobalMethods; +import com.google.devtools.build.docgen.annot.GlobalMethods.Environment; import com.google.devtools.build.lib.cmdline.Label; import javax.annotation.Nullable; import net.starlark.java.annot.Param; @@ -40,6 +42,8 @@ + "(i.e. for macros, not for rule implementations). Attributes will ignore " + "None values, and treat them as if the attribute was unset.
      " + "The following functions are also available:") +// Methods in this class are also available at the top level in BUILD files. +@GlobalMethods(environment = Environment.BUILD) public interface StarlarkNativeModuleApi extends StarlarkValue { @StarlarkMethod( @@ -246,19 +250,20 @@ NoneType exportsFiles(Sequence srcs, Object visibility, Object licenses, Star @StarlarkMethod( name = "package_relative_label", doc = - "Converts the input string into a Label object, in the context of the" - + " package currently being initialized (that is, the BUILD file for" - + " which the current macro is executing). If the input is already a" - + " Label, it is returned unchanged.

      This function may only be called" - + " while evaluating a BUILD file and the macros it directly or indirectly calls; it" - + " may not be called in (for instance) a rule implementation function.

      The result" - + " of this function is the same Label value as would be produced by" - + " passing the given string to a label-valued attribute of a target declared in the" - + " BUILD file.

      Usage note: The difference between this function and Label() is that Label() uses the" - + " context of the package of the .bzl file that called it, not the" - + " package of the BUILD file. Use Label() when you need to" - + " refer to a fixed target that is hardcoded into the macro, such as a compiler. Use" + "Converts the input string into a Label object, in" + + " the context of the package currently being initialized (that is, the" + + " BUILD file for which the current macro is executing). If the input" + + " is already a Label, it is returned unchanged.

      This function may" + + " only be called while evaluating a BUILD file and the macros it directly or" + + " indirectly calls; it may not be called in (for instance) a rule implementation" + + " function.

      The result of this function is the same Label value as" + + " would be produced by passing the given string to a label-valued attribute of a" + + " target declared in the BUILD file.

      Usage note: The difference between" + + " this function and Label() is" + + " that Label() uses the context of the package of the" + + " .bzl file that called it, not the package of the BUILD" + + " file. Use Label() when you need to refer to a fixed target that is" + + " hardcoded into the macro, such as a compiler. Use" + " package_relative_label() when you need to normalize a label string" + " supplied by the BUILD file to a Label object. (There is no way to" + " convert a string to a Label in the context of a package other than" diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java index 57063802c14bac..9567c0035a9bcb 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleContextApi.java @@ -64,38 +64,39 @@ public interface StarlarkRuleContextApistruct containing executable files defined in label type attributes marked as executable=True. The struct " - + "fields correspond to the attribute names. Each value in the struct is either a File or None. If an optional " - + "attribute is not specified in the rule then the corresponding struct value is " - + "None. If a label type is not marked as executable=True, no " - + "corresponding struct field is generated. See example of use."; + "A struct containing executable files defined in label type attributes marked as executable=True. The" + + " struct fields correspond to the attribute names. Each value in the struct is either a" + + " File or None. If an" + + " optional attribute is not specified in the rule then the corresponding struct value" + + " is None. If a label type is not marked as executable=True," + + " no corresponding struct field is generated. See" + + " example of use."; String FILES_DOC = - "A struct containing files defined in label or label list type attributes. The struct fields" - + " correspond to the attribute names. The struct values are list of Files. It is a shortcut for:struct containing files defined in label or label list type attributes. The struct" + + " fields correspond to the attribute names. The struct values are list of" + + " Files. It is a shortcut for:[f for t in ctx.attr.<ATTR> for f in t.files] In" + " other words, use files to access the " - + " default outputs of a dependency. default" + + " outputs of a dependency. See" + " example of use."; String FILE_DOC = - "A struct containing files defined in label type" - + " attributes marked as allow_single_file. The" - + " struct fields correspond to the attribute names. The struct value is always a File or None. If an optional attribute" - + " is not specified in the rule then the corresponding struct value is" - + " None. If a label type is not marked as allow_single_file," - + " no corresponding struct field is generated. It is a shortcut for:list(ctx.attr.<ATTR>.files)[0]In other words, use" - + " file to access the (singular) struct containing files defined in label type attributes marked as allow_single_file." + + " The struct fields correspond to the attribute names. The struct value is always a File or None. If an" + + " optional attribute is not specified in the rule then the corresponding struct value" + + " is None. If a label type is not marked as" + + " allow_single_file, no corresponding struct field is generated. It is a" + + " shortcut for:

      list(ctx.attr.<ATTR>.files)[0]
      In" + + " other words, use file to access the (singular) default" + " output of a dependency. See" @@ -105,8 +106,8 @@ public interface StarlarkRuleContextApiattributes. The values are" + " provided by the user (if not, a default value is used). The attributes of the struct" + " and the types of their values correspond to the keys and values of the attrs dict provided to the rule function. attrs dict provided to the rule function. See" + " example of use."; String SPLIT_ATTR_DOC = @@ -119,34 +120,36 @@ public interface StarlarkRuleContextApiFile objects. See the File objects. See the Rules page for more information" + " and examples.

      This field does not exist on aspect contexts, since aspects do not" + " have predeclared outputs.

      The fields of this object are defined as follows. It is" + " an error if two outputs produce the same field name or have the same label.

      • " - + " If the rule declares an outputs" - + " dict, then for every entry in the dict, there is a field whose name is the key and" - + " whose value is the corresponding File.
      • For every attribute of type attr.output that the rule declares, there is" - + " a field whose name is the attribute's name. If the target specified a label for that" - + " attribute, then the field value is the corresponding File; otherwise the" - + " field value is None.
      • For every attribute of type attr.output_list that the rule" - + " declares, there is a field whose name is the attribute's name. The field value is a" - + " list of File objects corresponding to the labels given for that" + + " If the rule declares an outputs dict, then for every" + + " entry in the dict, there is a field whose name is the key and whose value is the" + + " corresponding File.
      • For every attribute of type attr.output that the rule" + + " declares, there is a field whose name is the attribute's name. If the target" + + " specified a label for that attribute, then the field value is the corresponding" + + " File; otherwise the field value is None.
      • For every" + + " attribute of type attr.output_list that the" + + " rule declares, there is a field whose name is the attribute's name. The field value" + + " is a list of File objects corresponding to the labels given for that" + " attribute in the target, or an empty list if the attribute was not specified in the" + " target.
      • (Deprecated) If the rule is marked executable or test, there is a field named" + + " href='../globals/bzl.html#rule.executable'>executable or test, there is a field named" + " \"executable\", which is the default executable. It is recommended that" + " instead of using this, you pass another file (either predeclared or not) to the" + " executable arg of DefaultInfo.
      "; + + " href='../providers/DefaultInfo.html'>DefaultInfo.
    "; @StarlarkMethod( name = "default_provider", structField = true, - doc = "Deprecated. Use DefaultInfo instead.") + doc = "Deprecated. Use DefaultInfo instead.") ProviderApi getDefaultProvider(); @StarlarkMethod( @@ -158,10 +161,10 @@ public interface StarlarkRuleContextApi_skylark_testable" - + " set to True, this returns an Actions provider representing all actions" - + " created so far for the current rule. For all other rules, returns" + "For rules with _skylark_testable set to" + + " True, this returns an Actions provider representing all" + + " actions created so far for the current rule. For all other rules, returns" + " None. Note that the provider is not updated when subsequent actions" + " are created, so you will have to call this function again if you wish to inspect" + " them.

    This is intended to help write tests for rule-implementation" @@ -206,7 +209,7 @@ public interface StarlarkRuleContextApi" + "The default configuration. See the " + "configuration type for more details.") BuildConfigurationApi getConfiguration() throws EvalException; @@ -223,17 +226,16 @@ public interface StarlarkRuleContextApitarget is provided, the " - + "rule specified by that Target. (If a non-rule or a Starlark rule Target is " - + "provided, this returns False.) Checks if the sources of the current rule " - + "(if no Target is provided) or the sources of Target should be instrumented " - + "based on the --instrumentation_filter and " - + "--instrument_test_targets config settings. " - + "This differs from coverage_enabled in the " - + "configuration, which notes whether coverage " - + "data collection is enabled for the entire run, but not whether a specific " - + "target should be instrumented.", + "Returns whether code coverage instrumentation should be generated when performing" + + " compilation actions for this rule or, if target is provided, the" + + " rule specified by that Target. (If a non-rule or a Starlark rule Target is" + + " provided, this returns False.) Checks if the sources of the current rule (if no" + + " Target is provided) or the sources of Target should be instrumented based on the" + + " --instrumentation_filter and --instrument_test_targets config settings. This" + + " differs from coverage_enabled in the configuration, which notes whether" + + " coverage data collection is enabled for the entire run, but not whether a" + + " specific target should be instrumented.", parameters = { @Param( name = "target", @@ -342,21 +344,16 @@ public interface StarlarkRuleContextApictx.actions.declare_file.
    " - + "Creates a file object. There are four possible signatures to this method:
      " - + "" - + "
    • new_file(filename): Creates a file object with the given filename in the " - + "current package.
      • " - + "" - + "
    • new_file(file_root, filename): Creates a file object with the given " - + "filename under the given file root.
      • " - + "" - + "
    • new_file(sibling_file, filename): Creates a file object in the same " - + "directory as the given sibling file.
      • " - + "" - + "
    • new_file(file_root, sibling_file, suffix): Creates a file object with same " - + "base name of the sibling_file but with different given suffix, under the given " - + "file root.

    " + "DEPRECATED. Use ctx.actions.declare_file." + + "
    Creates a file object. There are four possible signatures to this" + + " method:
    • new_file(filename): Creates a file object with the given" + + " filename in the current package.
    • new_file(file_root, filename): Creates a" + + " file object with the given filename under the given file root.
      • " + + "
    • new_file(sibling_file, filename): Creates a file object in the same directory" + + " as the given sibling file.
    • new_file(file_root, sibling_file, suffix):" + + " Creates a file object with same base name of the sibling_file but with different" + + " given suffix, under the given file root.

    " + DOC_NEW_FILE_TAIL, parameters = { @Param( @@ -405,19 +402,16 @@ boolean checkPlaceholders(String template, Sequence allowedPlaceholders) // < @StarlarkMethod( name = "expand_make_variables", doc = - "Deprecated. Use ctx.var to access the variables " - + "instead.
    Returns a string after expanding all references to \"Make " - + "variables\". The " - + "variables must have the following format: $(VAR_NAME). Also, " - + "$$VAR_NAME expands to $VAR_NAME. " - + "Examples:" - + "
    \n"
-              + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"})  "
-              + "# == \"Hi\"\n"
+          "Deprecated. Use ctx.var to access the"
+              + " variables instead.
    Returns a string after expanding all references to \"Make"
+              + " variables\". The variables must have the following format:"
+              + " $(VAR_NAME). Also, $$VAR_NAME expands to"
+              + " $VAR_NAME. Examples:
    \n"
+              + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"})  # =="
+              + " \"Hi\"\n"
               + "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {})  # == \"$PWD\"\n"
-              + "
    "
-              + "Additional variables may come from other places, such as configurations. Note "
-              + "that this function is experimental.",
+              + "
    Additional variables may come from other places, such as configurations." + + " Note that this function is experimental.", parameters = { @Param( name = "attribute_name", diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java index 290a1e8a74eedb..6dedd3873a78fa 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java @@ -36,29 +36,26 @@ * functions. */ @GlobalMethods(environment = Environment.BZL) -public interface StarlarkRuleFunctionsApi { +public interface StarlarkRuleFunctionsApi { String EXEC_COMPATIBLE_WITH_PARAM = "exec_compatible_with"; String TOOLCHAINS_PARAM = "toolchains"; String PROVIDES_DOC = - "A list of providers that the implementation function must return." - + "" - + "

    It is an error if the implementation function omits any of the types of providers " - + "listed here from its return value. However, the implementation function may return " - + "additional providers not listed here." - + "" - + "

    Each element of the list is an *Info object returned by " - + "provider(), except that a legacy " - + "provider is represented by its string name instead." - + "" - + "When a target of the rule is used as a dependency for a target that declares a " - + "required provider, it is not necessary to specify that provider here. It is enough " - + "that the implementation function returns it. However, it is considered best " - + "practice to specify it, even though this is not required. The " - + "required_providers field " - + "of an aspect does, however, require that providers " - + "are specified here."; + "A list of providers that the implementation function must return." // + + "

    It is an error if the implementation function omits any of the types of providers" + + " listed here from its return value. However, the implementation function may return" + + " additional providers not listed here." // + + "

    Each element of the list is an *Info object returned by provider(), except that a legacy" + + " provider is represented by its string name instead.When a target of the rule is used" + + " as a dependency for a target that declares a required provider, it is not necessary" + + " to specify that provider here. It is enough that the implementation function returns" + + " it. However, it is considered best practice to specify it, even though this is not" + + " required. The required_providers" + + " field of an aspect does, however, require" + + " that providers are specified here."; @StarlarkMethod( name = "provider", @@ -76,10 +73,10 @@ public interface StarlarkRuleFunctionsApi { + " ..." // + "

    See Rules" + " (Providers) for a comprehensive guide on how to use providers." // - + "

    Returns a Provider callable " - + "value if init is not specified." // + + "

    Returns a Provider" + + " callable value if init is not specified." // + "

    If init is specified, returns a tuple of 2 elements: a Provider callable value and a" + + " href='../builtins/Provider.html'>Provider callable value and a" + " raw constructor callable value. See " + " Rules (Custom initialization of custom providers) and the discussion of the" @@ -165,8 +162,9 @@ public interface StarlarkRuleFunctionsApi { + "

    NB: the above steps imply that an error occurs if *args or" + " **kwargs does not match init's signature, or the" + " evaluation of init's body fails (perhaps intentionally via a" - + " call to fail()), or if the return value" - + " of init is not a dictionary with the expected schema." // + + " call to fail()), or" + + " if the return value of init is not a dictionary with the" + + " expected schema." // + "

    In this way, the init callback generalizes normal provider" + " construction by allowing positional arguments and arbitrary logic for" + " preprocessing and validation. It does not enable circumventing the" @@ -207,10 +205,10 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) name = "implementation", named = true, doc = - "the Starlark function implementing this rule, must have exactly one parameter: " - + "ctx. The function is called during the analysis " - + "phase for each instance of the rule. It can access the attributes " - + "provided by the user. It must create actions to generate all the declared " + "the Starlark function implementing this rule, must have exactly one parameter: ctx. The function is called during the" + + " analysis phase for each instance of the rule. It can access the attributes" + + " provided by the user. It must create actions to generate all the declared " + "outputs."), @Param( name = "test", @@ -233,15 +231,15 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) named = true, defaultValue = "None", doc = - "dictionary to declare all the attributes of the rule. It maps from an attribute " - + "name to an attribute object (see attr module). " - + "Attributes starting with _ are private, and can be used to " - + "add an implicit dependency on a label. The attribute name is " - + "implicitly added and must not be specified. Attributes " - + "visibility, deprecation, tags, " - + "testonly, and features are implicitly added and " - + "cannot be overridden. Most rules need only a handful of attributes. To " - + "limit memory usage, the rule function imposes a cap on the size of attrs."), + "dictionary to declare all the attributes of the rule. It maps from an attribute" + + " name to an attribute object (see attr" + + " module). Attributes starting with _ are private, and can be" + + " used to add an implicit dependency on a label. The attribute" + + " name is implicitly added and must not be specified. Attributes" + + " visibility, deprecation, tags," + + " testonly, and features are implicitly added and" + + " cannot be overridden. Most rules need only a handful of attributes. To" + + " limit memory usage, the rule function imposes a cap on the size of attrs."), // TODO(bazel-team): need to give the types of these builtin attributes @Param( name = "outputs", @@ -258,14 +256,14 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) "This parameter has been deprecated. Migrate rules to use" + " OutputGroupInfo or attr.output instead.

    A" + " schema for defining predeclared outputs. Unlike output and output_list attributes, the" - + " user does not specify the labels for these files. See the Rules page for more on" - + " predeclared outputs.

    The value of this argument is either a dictionary or" - + " a callback function that produces a dictionary. The callback works similar" - + " to computed dependency attributes: The function's parameter names are" - + " matched against the rule's attributes, so for example if you pass" + + " href='../toplevel/attr.html#output'>output and output_list" + + " attributes, the user does not specify the labels for these files. See the" + + " Rules page for more" + + " on predeclared outputs.

    The value of this argument is either a dictionary" + + " or a callback function that produces a dictionary. The callback works" + + " similar to computed dependency attributes: The function's parameter names" + + " are matched against the rule's attributes, so for example if you pass" + " outputs = _my_func with the definition def" + " _my_func(srcs, deps): ..., the function has access to the attributes" + " srcs and deps. Whether the dictionary is" @@ -274,10 +272,10 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) + " identifier and the value is a string template that determines the output's" + " label. In the rule's implementation function, the identifier becomes the" + " field name used to access the output's File in ctx.outputs. The output's label" - + " has the same package as the rule, and the part after the package is" - + " produced by substituting each placeholder of the form" + + " href='../builtins/File.html'>File in ctx.outputs. The" + + " output's label has the same package as the rule, and the part after the" + + " package is produced by substituting each placeholder of the form" + " \"%{ATTR}\" with a string formed from the value of the" + " attribute ATTR:

    • String-typed attributes are substituted" + " verbatim.
    • Label-typed attributes become the part of the label after the" @@ -337,14 +335,12 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) named = true, defaultValue = "False", doc = - "(Experimental)

      " - + "If true, this rule will expose its actions for inspection by rules that " - + "depend on it via an Actions " - + "provider. The provider is also available to the rule itself by calling " - + "ctx.created_actions()." - + "

      " - + "This should only be used for testing the analysis-time behavior of " - + "Starlark rules. This flag may be removed in the future."), + "(Experimental)

      If true, this rule will expose its actions for" + + " inspection by rules that depend on it via an Actions provider." + + " The provider is also available to the rule itself by calling ctx.created_actions()." + + "

      This should only be used for testing the analysis-time behavior of" + + " Starlark rules. This flag may be removed in the future."), @Param( name = TOOLCHAINS_PARAM, allowedTypes = {@ParamType(type = Sequence.class, generic1 = Object.class)}, @@ -405,7 +401,7 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) + " This supersedes the value of test
    • The rule" + " implementation function may not register actions. Instead, it must register" + " a pass/fail result via providing AnalysisTestResultInfo.
    "), + + " href='../providers/AnalysisTestResultInfo.html'>AnalysisTestResultInfo."), @Param( name = "build_setting", allowedTypes = { @@ -416,12 +412,12 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) named = true, positional = false, doc = - "If set, describes what kind of " - + "build " - + "setting this rule is. See the " - + "config module. If this is " - + "set, a mandatory attribute named \"build_setting_default\" is automatically " - + "added to this rule, with a type corresponding to the value passed in here."), + "If set, describes what kind of build setting this" + + " rule is. See the config" + + " module. If this is set, a mandatory attribute named" + + " \"build_setting_default\" is automatically added to this rule, with a type" + + " corresponding to the value passed in here."), @Param( name = "cfg", defaultValue = "None", @@ -441,7 +437,7 @@ Object provider(Object doc, Object fields, Object init, StarlarkThread thread) positional = false, doc = "Dict of execution group name (string) to exec_groups. If set," + + " href='../globals/bzl.html#exec_group'>exec_groups. If set," + " allows rules to run actions on multiple execution platforms within a" + " single target. See execution groups" + " documentation for more info."), @@ -515,12 +511,12 @@ StarlarkCallable rule( name = "implementation", named = true, doc = - "A Starlark function that implements this aspect, with exactly two parameters: " - + "Target (the target to which the aspect is " - + "applied) and ctx (the rule context which the " - + "target is created from). Attributes of the target are available via the " - + "ctx.rule field. This function is evaluated during the " - + "analysis phase for each application of an aspect to a target."), + "A Starlark function that implements this aspect, with exactly two parameters: Target (the target to which the aspect" + + " is applied) and ctx (the rule context" + + " which the target is created from). Attributes of the target are available" + + " via the ctx.rule field. This function is evaluated during the" + + " analysis phase for each application of an aspect to a target."), @Param( name = "attr_aspects", allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)}, @@ -541,19 +537,17 @@ StarlarkCallable rule( named = true, defaultValue = "None", doc = - "A dictionary declaring all the attributes of the aspect. It maps from an " - + "attribute name to an attribute object, like `attr.label` or `attr.string` " - + "(see attr module). Aspect attributes are " - + "available to implementation function as fields of ctx " - + "parameter. " - + "" - + "

    Implicit attributes starting with _ must have default " - + "values, and have type label or label_list. " - + "" - + "

    Explicit attributes must have type string, and must use " - + "the values restriction. Explicit attributes restrict the " - + "aspect to only be used with rules that have attributes of the same " - + "name, type, and valid values according to the restriction."), + "A dictionary declaring all the attributes of the aspect. It maps from an attribute" + + " name to an attribute object, like `attr.label` or `attr.string` (see attr module). Aspect attributes are" + + " available to implementation function as fields of ctx" + + " parameter.

    Implicit attributes starting with _ must have" + + " default values, and have type label or" + + " label_list.

    Explicit attributes must have type" + + " string, and must use the values restriction." + + " Explicit attributes restrict the aspect to only be used with rules that" + + " have attributes of the same name, type, and valid values according to the" + + " restriction."), @Param( name = "required_providers", named = true, @@ -686,7 +680,7 @@ StarlarkCallable rule( positional = false, doc = "Dict of execution group name (string) to exec_groups. If set," + + " href='../globals/bzl.html#exec_group'>exec_groups. If set," + " allows aspects to run actions on multiple execution platforms within a" + " single instance. See execution groups" + " documentation for more info.") @@ -716,10 +710,9 @@ StarlarkAspectApi aspect( doc = "Converts a label string into a Label object, in the context of the package" + " where the calling .bzl source file lives. If the given value is" - + " already a Label, it is returned unchanged." - + "

    For macros, a related function," - + " native.package_relative_label()," + + " already a Label, it is returned unchanged.

    For macros, a related" + + " function, native.package_relative_label()," + " converts the input into a Label in the context of the package" + " currently being constructed. Use that function to mimic the string-to-label" + " conversion that is automatically done by label-valued rule attributes.", diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java index e7315c4016516c..8004c6ef03f337 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/TemplateDictApi.java @@ -62,7 +62,7 @@ public interface TemplateDictApi extends StarlarkValue { doc = "A delimiter string used to join together the strings obtained from applying " + "map_each, in the same manner as " - + "string.join()."), + + "string.join()."), @Param( name = "map_each", allowedTypes = { diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java index 15908e12a70e42..6a06a5a060f814 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformApi.java @@ -27,20 +27,19 @@ "Corresponds to Xcode's notion of a platform as would be found in" + " Xcode.app/Contents/Developer/Platforms. Each platform represents an" + " Apple platform type (such as iOS or tvOS) combined with one or more related CPU" - + " architectures. For example, the iOS simulator platform supports" - + " x86_64 and i386 architectures.

    Specific instances of" - + " this type can be retrieved from the fields of the apple_common.platform struct:

      " - + "
    • apple_common.platform.ios_device
      • " + + " architectures. For example, the iOS simulator platform supports x86_64" + + " and i386 architectures.

      Specific instances of this type can be" + + " retrieved from the fields of the apple_common.platform" + + " struct:

      • apple_common.platform.ios_device
        • " + "
      • apple_common.platform.ios_simulator
        • " + "
      • apple_common.platform.macos
        • " + "
      • apple_common.platform.tvos_device
        • " + "
      • apple_common.platform.tvos_simulator
        • " - + "
      • apple_common.platform.watchos_device
        • " - + "
      • apple_common.platform.watchos_simulator

      More commonly," - + " however, the apple configuration fragment has" - + " fields/methods that allow rules to determine the platform for which a target is" - + " being built.

      Example:

      \n"
+            + "
    • apple_common.platform.watchos_device
    • apple_common.platform.watchos_simulator

    More" + + " commonly, however, the apple configuration" + + " fragment has fields/methods that allow rules to determine the platform for which a" + + " target is being built.

    Example:

    \n"
             + "p = apple_common.platform.ios_device\n"
             + "print(p.name_in_plist)  # 'iPhoneOS'\n"
             + "
    ") diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java index e110ad94c78198..8ad811e7176d76 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/ApplePlatformTypeApi.java @@ -27,13 +27,12 @@ + " distinct from a \"platform\", which is the platform type combined with one or more" + " CPU architectures.

    Specific instances of this type can be retrieved by accessing" + " the fields of the apple_common.platform_type:

      " + + " href='../toplevel/apple_common.html#platform_type'>apple_common.platform_type:
        " + "
      • apple_common.platform_type.ios
        • " + "
      • apple_common.platform_type.macos
        • " - + "
      • apple_common.platform_type.tvos
        • " - + "
      • apple_common.platform_type.watchos

      Likewise, the" - + " platform type of an existing platform value can be retrieved using its" + + "

    • apple_common.platform_type.tvos
    • apple_common.platform_type.watchos

    Likewise," + + " the platform type of an existing platform value can be retrieved using its" + " platform_type field.

    Platform types can be converted to a lowercase" + " string (e.g., ios or macos) using the str function.") + + " href='../globals/all.html#str'>str function.") public interface ApplePlatformTypeApi extends StarlarkValue {} diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java index e40ba48ed642d0..db5f3a1bff6fa7 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java @@ -23,7 +23,7 @@ /** Interface for a utility module involving the Apple toolchain. */ @StarlarkBuiltin( name = "apple_toolchain", - category = DocCategory.TOP_LEVEL_MODULE, + category = DocCategory.BUILTIN, doc = "Utilities for resolving items from the Apple toolchain.") public interface AppleToolchainApi> extends StarlarkValue { diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java index 4b3fcfe8b853c6..df710d5b37cbf0 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java @@ -106,8 +106,9 @@ ConfigurationTransitionApi transition( + " analysis_test = True. Such rules are restricted in capabilities (for" + " example, the size of their dependency tree is limited), so transitions created" + " using this function are limited in potential scope as compared to transitions" - + " created using transition.

    This function is" - + " primarily designed to facilitate the transition().

    This" + + " function is primarily designed to facilitate the Analysis Test Framework core" + " library. See its documentation (or its implementation) for best practices.", parameters = { diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java index 986f64f97b4960..bc192ff5791686 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/ProviderApi.java @@ -33,12 +33,12 @@ + " Note: Some providers, defined internally, do not allow instance creation" + " " + "

  • It is a key to access a provider instance on a" - + " Target" + + " Target" + "
    DataInfo = provider()\n"
             + "def _rule_impl(ctx)\n"
             + "  ... ctx.attr.dep[DataInfo]
    " + "
    • " + " " + "Create a new Provider using the " - + "provider function.") + + "provider function.") public interface ProviderApi extends StarlarkValue {} diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java index 4a7c7f3fe82275..3b7485c5b79712 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core/TransitiveInfoCollectionApi.java @@ -24,25 +24,26 @@ category = DocCategory.BUILTIN, doc = "The BUILD target for a dependency. Appears in the fields of ctx.attr corresponding to ctx.attr corresponding to dependency" - + " attributes (label or label_list). Has the following fields:\n" + + " attributes (label or" + + " label_list). Has the" + + " following fields:\n" // + "
      \n" // + "

    • label

      \n" // - + "Label Target.label
      \n" // + + "Label Target.label
      \n" // + "The identifier of the target.
      • \n" // // + "

    • files

      \n" // - + "depset Target.files
      \n" // - + "The set of Files in the default outputs for " - + "this target. Equivalent to " - + "target[DefaultInfo].files.
      • \n" // + + "depset Target.files
      \n" // + + "The set of Files in the default" + + " outputs for this target. Equivalent to target[DefaultInfo].files.\n" // // + "

    • aspect_ids

      \n" // - + "list Target.aspect_ids
      \n" // - + "The list of aspect_ids " + + "list Target.aspect_ids
      \n" // + + "The list of aspect_ids " + "applied to this target.
      • \n" // // + "

    • Providers

      \n" // @@ -52,9 +53,9 @@ + " the in operator (SomeInfo in target).
      \n" // + "
      \n" // + "If the rule's implementation function returns a struct instead of a list of Provider instances, the struct's fields can be" - + " accessed via the corresponding fields of the Target" + + " href='../builtins/struct.html'>struct instead of a list of Provider instances, the struct's fields" + + " can be accessed via the corresponding fields of the Target" + " (target.some_legacy_info). This behavior is" + " deprecated.
      • \n" // diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java index fd841e3105b375..93a866e216c37b 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcCompilationContextApi.java @@ -31,7 +31,7 @@ */ @StarlarkBuiltin( name = "CompilationContext", - category = DocCategory.PROVIDER, + category = DocCategory.BUILTIN, doc = "Immutable store of information needed for C++ compilation that is aggregated across " + "dependencies.") diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java index eff698beb3e59b..e412cc3bca5f7d 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcLinkingOutputsApi.java @@ -37,9 +37,7 @@ public interface CcLinkingOutputsApi< name = "library_to_link", structField = true, allowReturnNones = true, - doc = - "LibraryToLink for including these outputs " - + "in further linking.", + doc = "LibraryToLink for including these outputs in further linking.", documented = true) @Nullable LibraryToLinkApi getLibraryToLink(); @@ -48,7 +46,7 @@ public interface CcLinkingOutputsApi< name = "executable", structField = true, allowReturnNones = true, - doc = "File object representing the linked executable.", + doc = "Represents the linked executable.", documented = true) @Nullable FileT getExecutable(); diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java index 8026fcf6039927..5054a6c32f3959 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppConfigurationApi.java @@ -99,7 +99,7 @@ public interface CppConfigurationApi" + "--custom_malloc option. Can be accessed with" - + " configuration_field" + + " configuration_field" + ":
      " + "
      attr.label(
      "
               + "    default = configuration_field(
      "
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java
index b362246ec35be8..569619d3201a0f 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaCommonApi.java
@@ -321,7 +321,7 @@ JavaInfoT createJavaCompileAction(
           "Runs ijar on a jar, stripping it of its method bodies. This helps reduce rebuilding "
               + "of dependent jars during any recompiles consisting only of simple changes to "
               + "method implementations. The return value is typically passed to "
-              + ""
+              + ""
               + "JavaInfo#compile_jar.",
       parameters = {
         @Param(name = "actions", named = true, doc = "ctx.actions"),
@@ -366,10 +366,10 @@ FileApi runIjar(
       doc =
           "Stamps a jar with a target label for add_dep support. "
               + "The return value is typically passed to "
-              + ""
+              + ""
               + "JavaInfo#compile_jar. "
               + "Prefer to use "
-              + "run_ijar "
+              + "run_ijar "
               + "when possible.",
       parameters = {
         @Param(name = "actions", named = true, doc = "ctx.actions"),
@@ -401,7 +401,7 @@ FileApi stampJar(
       doc =
           "Packs sources and source jars into a single source jar file. "
               + "The return value is typically passed to"
-              + "
      "
+              + "
      "
               + "JavaInfo#source_jar
      ."
               + "At least one of parameters output_jar or output_source_jar is required.",
       parameters = {
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
index f9ccc381e67057..271de296abfeab 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
@@ -71,16 +71,16 @@ public interface JavaInfoApi<
           "Returns the regular, full compile time Jars required by this target directly. They can"
               + " be "
+              + " href=\"#compile_jars\">JavaInfo.compile_jars
    " + "

    Note: JavaInfo.compile_jars can return" + + " href=\"#compile_jars\">JavaInfo.compile_jars can return" + " a mix of interface Jars and regular Jars.

    Only use this method if interface" + " Jars don't work with your rule set(s) (e.g. some Scala targets) If you're" + " working with Java-only targets it's preferable to use interface Jars via" + " JavaInfo.compile_jars", + + " href=\"#compile_jars\">JavaInfo.compile_jars", structField = true) Depset getFullCompileTimeJars(); @@ -133,7 +133,7 @@ public interface JavaInfoApi< name = "transitive_deps", doc = "Deprecated: Please use JavaInfo.transitive_compile_time_jars" + + "href=\"#transitive_compile_time_jars\">JavaInfo.transitive_compile_time_jars" + " instead. It returns the same value.", structField = true) Depset /**/ getTransitiveDeps(); @@ -142,7 +142,7 @@ public interface JavaInfoApi< name = "transitive_runtime_deps", doc = "Deprecated: please use JavaInfo.transitive_runtime_jars" + + " href=\"#transitive_runtime_jars\">JavaInfo.transitive_runtime_jars" + " instead. It returns the same value", structField = true) Depset /**/ getTransitiveRuntimeDeps(); @@ -198,10 +198,10 @@ interface JavaInfoProviderApi extends ProviderApi { doc = "A jar that is added as the compile-time dependency in lieu of " + "output_jar. Typically this is the ijar produced by " - + "" + + "" + "run_ijar. " + "If you cannot use ijar, consider instead using the output of " - + "" + + "" + "stamp_ijar. If you do not wish to use either, " + "you can simply pass output_jar. " + "There are a couple of special cases when this parameter may be set to " @@ -216,9 +216,10 @@ interface JavaInfoProviderApi extends ProviderApi { named = true, defaultValue = "None", doc = - "The source jar that was used to create the output jar. " - + "Use " - + "pack_sources to produce this source jar."), + "The source jar that was used to create the output jar. Use pack_sources" + + " to produce this source jar."), @Param( name = "compile_jdeps", allowedTypes = { diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java index 418a0773520fc2..7932e1fbf5c5e6 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java @@ -66,10 +66,15 @@ public interface AppleCommonApi< name = "platform_type", doc = "An enum-like struct that contains the following fields corresponding to Apple platform " - + "types:

    • ios
    • macos
      • " - + "
    • tvos
    • watchos

    These values can" - + " be passed to methods that expect a platform type, like the 'apple' configuration" - + " fragment's multi_arch_platform" + + "types:

      " // + + "
    • ios
      • " // + + "
    • macos
      • " // + + "
    • tvos
      • " // + + "
    • watchos
      • " // + + "

    " // + + "These values can be passed to methods that expect a platform type, like the" + + " 'apple' configuration fragment's multi_arch_platform" + " method.

    Example:

    \n"
               + "ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios)\n"
               + "
    ", @@ -87,17 +92,17 @@ public interface AppleCommonApi< name = "platform", doc = "An enum-like struct that contains the following fields corresponding to Apple " - + "platforms:
      " - + "
    • ios_device
      • " - + "
    • ios_simulator
      • " - + "
    • macos
      • " - + "
    • tvos_device
      • " - + "
    • tvos_simulator
      • " - + "
    • watchos_device
      • " - + "
    • watchos_simulator
      • " - + "

    " + + "platforms:

      " // + + "
    • ios_device
      • " // + + "
    • ios_simulator
      • " // + + "
    • macos
      • " // + + "
    • tvos_device
      • " // + + "
    • tvos_simulator
      • " // + + "
    • watchos_device
      • " // + + "
    • watchos_simulator
      • " // + + "

    " // + "These values can be passed to methods that expect a platform, like " - + "" + + "" + "XcodeVersionConfig.sdk_version_for_platform.", structField = true) StructApi getPlatformStruct(); @@ -177,10 +182,10 @@ public interface AppleCommonApi< @StarlarkMethod( name = "apple_host_system_env", doc = - "Returns a dict of environment variables that should be set " - + "for actions that need to run build tools on an Apple host system, such as the " - + " version of Xcode that should be used. The keys are variable names and the values " - + " are their corresponding values.", + "Returns a dict of environment variables that should be" + + " set for actions that need to run build tools on an Apple host system, such as the" + + " version of Xcode that should be used. The keys are variable names and the values" + + " are their corresponding values.", parameters = { @Param( name = "xcode_config", @@ -427,7 +432,7 @@ StructApi linkMultiArchStaticLibrary( @StarlarkMethod( name = "dotted_version", - doc = "Creates a new DottedVersion instance.", + doc = "Creates a new DottedVersion instance.", parameters = { @Param(name = "version", doc = "The string representation of the DottedVersion.") }) diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java index cbe266c49eb7ae..d2b1f8293fa619 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform/PlatformCommonApi.java @@ -29,21 +29,24 @@ public interface PlatformCommonApi extends StarlarkValue { @StarlarkMethod( name = "TemplateVariableInfo", doc = - "The constructor/key for the " + "The constructor/key for the " + "TemplateVariableInfo provider.", structField = true) ProviderApi getMakeVariableProvider(); @StarlarkMethod( name = "ToolchainInfo", - doc = "The constructor/key for the ToolchainInfo provider.", + doc = + "The constructor/key for the ToolchainInfo" + + " provider.", structField = true) ProviderApi getToolchainInfoConstructor(); @StarlarkMethod( name = "PlatformInfo", doc = - "The constructor/key for the PlatformInfo provider." + "The constructor/key for the PlatformInfo" + + " provider." + PlatformInfoApi.EXPERIMENTAL_WARNING, structField = true) ProviderApi getPlatformInfoConstructor(); @@ -51,7 +54,7 @@ public interface PlatformCommonApi extends StarlarkValue { @StarlarkMethod( name = "ConstraintSettingInfo", doc = - "The constructor/key for the " + "The constructor/key for the " + "ConstraintSettingInfo provider." + PlatformInfoApi.EXPERIMENTAL_WARNING, structField = true) @@ -60,7 +63,7 @@ public interface PlatformCommonApi extends StarlarkValue { @StarlarkMethod( name = "ConstraintValueInfo", doc = - "The constructor/key for the " + "The constructor/key for the " + "ConstraintValueInfo provider." + PlatformInfoApi.EXPERIMENTAL_WARNING, structField = true) diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java index 6143696d7e30ab..85b612f88adf4a 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/proto/ProtoCommonApi.java @@ -27,10 +27,8 @@ name = "proto_common", category = DocCategory.TOP_LEVEL_MODULE, doc = - "Utilities for protocol buffers. " - + "

    " - + "Please consider using `load(\"@rules_proto//proto:defs.bzl\", \"proto_common\")` " - + "to load this symbol from " - + "rules_proto" + "Utilities for protocol buffers.

    Please consider using" + + " load(\"@rules_proto//proto:defs.bzl\", \"proto_common\") to load this" + + " symbol from rules_proto." + "

    ") public interface ProtoCommonApi extends StarlarkValue {} diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java index d1ad2dc04f4d03..b0aa1b192b27cf 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java @@ -47,8 +47,8 @@ public interface RepositoryModuleApi { name = "implementation", named = true, doc = - "the function that implements this rule. Must have a single parameter," - + " repository_ctx. The" + "the function that implements this rule. Must have a single parameter, repository_ctx. The" + " function is called during the loading phase for each instance of the" + " rule."), @Param( @@ -60,7 +60,7 @@ public interface RepositoryModuleApi { defaultValue = "None", doc = "dictionary to declare all the attributes of the rule. It maps from an attribute " - + "name to an attribute object (see attr " + + "name to an attribute object (see attr " + "module). Attributes starting with _ are private, and can be " + "used to add an implicit dependency on a label to a file (a repository " + "rule cannot depend on a generated artifact). The attribute " @@ -133,16 +133,16 @@ StarlarkCallable repositoryRule( named = true, doc = "The function that implements this module extension. Must take a single parameter," - + " module_ctx. The function is" - + " called once at the beginning of a build to determine the set of available" - + " repos."), + + " module_ctx. The" + + " function is called once at the beginning of a build to determine the set of" + + " available repos."), @Param( name = "tag_classes", defaultValue = "{}", doc = "A dictionary to declare all the tag classes used by the extension. It maps from" + " the name of the tag class to a tag_class object.", + + " href=\"../builtins/tag_class.html\">tag_class     object.", named = true, positional = false), @Param( @@ -174,8 +174,8 @@ Object moduleExtension( named = true, doc = "A dictionary to declare all the attributes of this tag class. It maps from an" - + " attribute name to an attribute object (see attr" - + " module)."), + + " attribute name to an attribute object (see attr module)."), @Param( name = "doc", defaultValue = "''", diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java index aacd6a8285cbff..30a47151a598ca 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageCommonApi.java @@ -44,10 +44,10 @@ public interface CoverageCommonApi< @StarlarkMethod( name = "instrumented_files_info", doc = - "Creates a new " - + "InstrumentedFilesInfo " - + "instance. Use this provider to communicate coverage-related attributes of the " - + "current build rule.", + "Creates a new InstrumentedFilesInfo" + + " instance. Use this provider to communicate coverage-related attributes of the" + + " current build rule.", parameters = { @Param(name = "ctx", positional = true, named = true, doc = "The rule context."), @Param( diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java index 5cfaffba11bc98..b3388ac31107dd 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/CoverageConfigurationApi.java @@ -38,7 +38,7 @@ public interface CoverageConfigurationApi extends StarlarkValue { + "#flag--coverage_output_generator\">" + "--coverage_output_generator option if coverage collection is" + " enabled, otherwise returns None. Can be accessed with" - + " configuration_field" + + " configuration_field" + ":
    " + "
    attr.label(
    "
               + "    default = configuration_field(
    "
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java
index 398673f2092a8c..dde7e541da7fb5 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/InstrumentedFilesInfoApi.java
@@ -28,9 +28,8 @@
         "Contains information about source files and instrumentation metadata files for rule"
             + " targets matched by --instrumentation_filter"
-            + " for purposes of code coverage"
-            + " data collection. When coverage data collection is enabled, a manifest"
+            + " for purposes of code"
+            + " coverage data collection. When coverage data collection is enabled, a manifest"
             + " containing the combined paths in instrumented_files and metadata_files are passed to the test"
@@ -45,21 +44,21 @@ public interface InstrumentedFilesInfoApi extends StructApi {
   @StarlarkMethod(
       name = "instrumented_files",
       doc =
-          "depset of File"
-              + " objects representing instrumented source files for this target and "
-              + "its dependencies.",
+          "depset of File objects representing"
+              + " instrumented source files for this target and its dependencies.",
       structField = true)
   Depset getInstrumentedFilesForStarlark();
 
   @StarlarkMethod(
       name = "metadata_files",
       doc =
-          "depset of File"
-              + " objects representing coverage metadata files for this target and its "
-              + "dependencies. These files contain additional information required to generate "
-              + "LCOV-format coverage output after the code is executed, e.g. the "
-              + ".gcno files generated when gcc is run with "
-              + "-ftest-coverage.",
+          "depset of File objects representing"
+              + " coverage metadata files for this target and its dependencies. These files contain"
+              + " additional information required to generate LCOV-format coverage output after the"
+              + " code is executed, e.g. the .gcno files generated when"
+              + " gcc is run with -ftest-coverage.",
       structField = true)
   Depset getInstrumentationMetadataFilesForStarlark();
 }
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java
index 37234c62048595..0f262d083e385a 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/TestingModuleApi.java
@@ -39,7 +39,9 @@ public interface TestingModuleApi extends StarlarkValue {
 
   @StarlarkMethod(
       name = "ExecutionInfo",
-      doc = "testing.ExecutionInfo provider key/constructor",
+      doc =
+          "testing.ExecutionInfo provider"
+              + " key/constructor",
       structField = true)
   ExecutionInfoApi.ExecutionInfoApiProvider executionInfo() throws EvalException;
 
@@ -93,12 +95,13 @@ RunEnvironmentInfoApi testEnvironment(
             named = true,
             doc =
                 "The Starlark function implementing this analysis test. It must have exactly one"
-                    + " parameter: ctx. The function is called during the"
-                    + " analysis phase. It can access the attributes declared by attrs"
-                    + " and populated via attr_values. The implementation function may"
-                    + " not register actions. Instead, it must register a pass/fail result"
-                    + " via providing AnalysisTestResultInfo."),
+                    + " parameter: ctx. The function is called"
+                    + " during the analysis phase. It can access the attributes declared by"
+                    + " attrs and populated via attr_values. The"
+                    + " implementation function may not register actions. Instead, it must register"
+                    + " a pass/fail result via providing AnalysisTestResultInfo"
+                    + "."),
         @Param(
             name = "attrs",
             allowedTypes = {
@@ -108,9 +111,10 @@ RunEnvironmentInfoApi testEnvironment(
             named = true,
             defaultValue = "None",
             doc =
-                "Dictionary declaring the attributes. See the rule call."
-                    + "Attributes are allowed to use configuration transitions defined using analysis_test_transition."),
+                "Dictionary declaring the attributes. See the rule call. Attributes are allowed to"
+                    + " use configuration transitions defined using analysis_test_transition."),
         @Param(
             name = "fragments",
             allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
@@ -125,8 +129,8 @@ RunEnvironmentInfoApi testEnvironment(
             named = true,
             defaultValue = "[]",
             doc =
-                "The set of toolchains the test requires. See the rule"
-                    + " call."),
+                "The set of toolchains the test requires. See the rule call."),
         @Param(
             name = "attr_values",
             allowedTypes = {@ParamType(type = Dict.class, generic1 = String.class)},
diff --git a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java
index 194fb45735cabe..07bf1a95bd5b38 100644
--- a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java
+++ b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/FakeStarlarkRuleFunctionsApi.java
@@ -19,7 +19,6 @@
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.build.lib.cmdline.LabelSyntaxException;
 import com.google.devtools.build.lib.starlarkbuildapi.ExecGroupApi;
-import com.google.devtools.build.lib.starlarkbuildapi.FileApi;
 import com.google.devtools.build.lib.starlarkbuildapi.StarlarkAspectApi;
 import com.google.devtools.build.lib.starlarkbuildapi.StarlarkRuleFunctionsApi;
 import com.google.devtools.build.skydoc.rendering.AspectInfoWrapper;
@@ -52,9 +51,9 @@
  * Fake implementation of {@link StarlarkRuleFunctionsApi}.
  *
  * 
    This fake hooks into the global {@code rule()} function, adding descriptors of calls of that
- * function to a {@link List} given in the class constructor.
    
+ * function to a {@link List} given in the class constructor.
  */
-public class FakeStarlarkRuleFunctionsApi implements StarlarkRuleFunctionsApi {
+public class FakeStarlarkRuleFunctionsApi implements StarlarkRuleFunctionsApi {
 
   private static final FakeDescriptor IMPLICIT_NAME_ATTRIBUTE_DESCRIPTOR =
       new FakeDescriptor(
diff --git a/src/main/java/net/starlark/java/eval/Dict.java b/src/main/java/net/starlark/java/eval/Dict.java
index ca3fcb78ed8fa9..a9e696a8b65dba 100644
--- a/src/main/java/net/starlark/java/eval/Dict.java
+++ b/src/main/java/net/starlark/java/eval/Dict.java
@@ -66,8 +66,8 @@
             + " dictionaries are mutable, and may be updated by assigning to d[k] or"
             + " by calling certain methods. Dictionaries are iterable; iteration yields the"
             + " sequence of keys in insertion order. Iteration order is unaffected by updating the"
-            + " value associated with an existing key, but is affected by removing then"
-            + " reinserting a key.\n"
+            + " value associated with an existing key, but is affected by removing then reinserting"
+            + " a key.\n"
             + "
    d = {0: 0, 2: 2, 1: 1}\n"
             + "[k for k in d]  # [0, 2, 1]\n"
             + "d.pop(2)\n"
@@ -79,8 +79,7 @@
             + "
      \n"
             + "
    1. A dictionary expression {k: v, ...} yields a new dictionary with"
             + " the specified key/value entries, inserted in the order they appear in the"
-            + " expression. Evaluation fails if any two key expressions yield the same"
-            + " value.\n"
+            + " expression. Evaluation fails if any two key expressions yield the same value.\n"
             + "
    2. A dictionary comprehension {k: v for vars in seq} yields a new"
             + " dictionary into which each key/value pair is inserted in loop iteration order."
             + " Duplicates are permitted: the first insertion of a given key determines its"
@@ -89,22 +88,20 @@
             + "{k: v for k, v in ((\"a\", 0), (\"b\", 1), (\"a\", 2))}  # {\"a\": 2, \"b\": 1}\n"
             + "{i: 2*i for i in range(3)}  # {0: 0, 1: 2, 2: 4}\n"
             + "
    \n"
-            + "
  • A call to the built-in dict function returns"
-            + " a dictionary containing the specified entries, which are inserted in argument"
-            + " order, positional arguments before named. As with comprehensions, duplicate keys"
-            + " are permitted.\n"
+            + "
  • A call to the built-in dict function"
+            + " returns a dictionary containing the specified entries, which are inserted in"
+            + " argument order, positional arguments before named. As with comprehensions,"
+            + " duplicate keys are permitted.\n"
             + "
  • The union expression x | y yields a new dictionary by combining two"
             + " existing dictionaries. If the two dictionaries have a key k in common,"
             + " the right hand side dictionary's value of the key (in other words,"
             + " y[k]) wins. The |= variant of the union operator modifies"
-            + " a dictionary in-place. Example:
    "
-            + "
    "
-            + "d = {\"foo\": \"FOO\", \"bar\": \"BAR\"} | {\"foo\": \"FOO2\", \"baz\": \"BAZ\"}\n"
+            + " a dictionary in-place. Example:
    d = {\"foo\":"
+            + " \"FOO\", \"bar\": \"BAR\"} | {\"foo\": \"FOO2\", \"baz\": \"BAZ\"}\n"
             + "# d == {\"foo\": \"FOO2\", \"bar\": \"BAR\", \"baz\": \"BAZ\"}\n"
             + "d = {\"a\": 1, \"b\": 2}\n"
             + "d |= {\"b\": 3, \"c\": 4}\n"
-            + "# d == {\"a\": 1, \"b\": 3, \"c\": 4}
    "
-            + "")
+            + "# d == {\"a\": 1, \"b\": 3, \"c\": 4}
    ")
 public class Dict
     implements Map,
         StarlarkValue,
diff --git a/src/main/java/net/starlark/java/eval/MethodLibrary.java b/src/main/java/net/starlark/java/eval/MethodLibrary.java
index df2467b73de23d..955248d742b348 100644
--- a/src/main/java/net/starlark/java/eval/MethodLibrary.java
+++ b/src/main/java/net/starlark/java/eval/MethodLibrary.java
@@ -479,7 +479,7 @@ public StarlarkInt intForStarlark(Object x, Object baseO) throws EvalException {
   @StarlarkMethod(
       name = "dict",
       doc =
-          "Creates a dictionary from an optional positional "
+          "Creates a dictionary from an optional positional "
               + "argument and an optional set of keyword arguments. In the case where the same key "
               + "is given multiple times, the last value will be used. Entries supplied via "
               + "keyword arguments are considered to come after entries supplied via the "
diff --git a/src/main/java/net/starlark/java/eval/StringModule.java b/src/main/java/net/starlark/java/eval/StringModule.java
index de84d4077d28c0..b4cdc137fd9a09 100644
--- a/src/main/java/net/starlark/java/eval/StringModule.java
+++ b/src/main/java/net/starlark/java/eval/StringModule.java
@@ -962,8 +962,8 @@ private static boolean substringEndsWith(String str, int start, int end, String
               + " to include a brace character in the literal text, it can be escaped by doubling:"
               + " {{ and }}A replacement field can be"
               + " either a name, a number, or empty. Values are converted to strings using the str function.
    #"
-              + " Access in order:\n"
+              + " href=\"../globals/all.html#str\">str function.# Access in order:\n"
               + "\"{} < {}\".format(4, 5) == \"4 < 5\"\n"
               + "# Access by position:\n"
               + "\"{1}, {0}\".format(2, 1) == \"1, 2\"\n"
diff --git a/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java b/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java
index 877a130854bff9..edf2763ff3ce81 100644
--- a/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java
+++ b/src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java
@@ -14,27 +14,29 @@
 package com.google.devtools.build.docgen;
 
 import static com.google.common.truth.Truth.assertThat;
-import static com.google.common.truth.Truth.assertWithMessage;
 
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Sets;
+import com.google.devtools.build.docgen.StarlarkDocumentationProcessor.Category;
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.docgen.annot.GlobalMethods;
 import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
 import com.google.devtools.build.docgen.annot.StarlarkConstructor;
-import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
 import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc;
+import com.google.devtools.build.docgen.starlark.StarlarkDoc;
 import com.google.devtools.build.docgen.starlark.StarlarkDocExpander;
+import com.google.devtools.build.docgen.starlark.StarlarkDocPage;
 import com.google.devtools.build.docgen.starlark.StarlarkMethodDoc;
 import com.google.devtools.build.lib.analysis.starlark.StarlarkModules;
 import com.google.devtools.build.lib.analysis.starlark.StarlarkRuleContext;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
-import java.util.ArrayList;
 import java.util.Collection;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
-import java.util.TreeMap;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.StarlarkBuiltin;
 import net.starlark.java.annot.StarlarkMethod;
@@ -72,39 +74,26 @@ public void testStarlarkRuleClassBuiltInItemsAreDocumented() throws Exception {
 
   private void checkStarlarkTopLevelEnvItemsAreDocumented(Map globals)
       throws Exception {
-    Map docMap = new HashMap<>();
-    Map modules =
-        new TreeMap<>(StarlarkDocumentationCollector.getAllModules(expander));
-    StarlarkBuiltinDoc topLevel =
-        modules.remove(StarlarkDocumentationCollector.getTopLevelModule().name());
-    for (StarlarkMethodDoc method : topLevel.getMethods()) {
-      docMap.put(method.getName(), method.getDocumentation());
-    }
-    for (Map.Entry entry : modules.entrySet()) {
-      docMap.put(entry.getKey(), entry.getValue().getDocumentation());
-    }
-
-    List undocumentedItems = new ArrayList<>();
-    // All built in variables are registered in the Starlark global environment.
-    for (String varname : globals.keySet()) {
-      if (docMap.containsKey(varname)) {
-        if (docMap.get(varname).isEmpty()) {
-          undocumentedItems.add(varname);
-        }
-      } else {
-        undocumentedItems.add(varname);
-      }
-    }
-
-    // These constants are currently undocumented.
-    // If they need documentation, the easiest approach would be
-    // to hard-code it in StarlarkDocumentationCollector.
-    undocumentedItems.remove("True");
-    undocumentedItems.remove("False");
-    undocumentedItems.remove("None");
-
-    assertWithMessage("Undocumented items: " + undocumentedItems)
-        .that(undocumentedItems)
+    ImmutableMap> allPages =
+        StarlarkDocumentationCollector.getAllDocPages(expander);
+    ImmutableSet documentedItems =
+        Stream.concat(
+                allPages.get(Category.GLOBAL_FUNCTION).stream()
+                    .flatMap(p -> p.getMethods().stream()),
+                allPages.entrySet().stream()
+                    .filter(e -> !e.getKey().equals(Category.GLOBAL_FUNCTION))
+                    .flatMap(e -> e.getValue().stream()))
+            .filter(m -> !m.getDocumentation().isEmpty())
+            .map(StarlarkDoc::getName)
+            .collect(ImmutableSet.toImmutableSet());
+
+    assertThat(
+            Sets.difference(
+                Sets.difference(globals.keySet(), documentedItems),
+                // These constants are currently undocumented.
+                // If they need documentation, the easiest approach would be
+                // to hard-code it in StarlarkDocumentationCollector.
+                ImmutableSet.of("True", "False", "None")))
         .containsExactlyElementsIn(DEPRECATED_UNDOCUMENTED_TOP_LEVEL_SYMBOLS);
   }
 
@@ -115,7 +104,7 @@ public void testDirectJavaMethodsAreGenerated() throws Exception {
   }
 
   /** MockClassA */
-  @StarlarkBuiltin(name = "MockClassA", doc = "MockClassA")
+  @StarlarkBuiltin(name = "MockClassA", category = DocCategory.BUILTIN, doc = "MockClassA")
   private static class MockClassA implements StarlarkValue {
     @StarlarkMethod(name = "get", doc = "MockClassA#get")
     public Integer get() {
@@ -124,7 +113,7 @@ public Integer get() {
   }
 
   /** MockClassD */
-  @StarlarkBuiltin(name = "MockClassD", doc = "MockClassD")
+  @StarlarkBuiltin(name = "MockClassD", category = DocCategory.BUILTIN, doc = "MockClassD")
   private static class MockClassD implements StarlarkValue {
     @StarlarkMethod(
         name = "test",
@@ -141,7 +130,7 @@ public Integer test(int a, int b, int c, int d) {
   }
 
   /** MockClassE */
-  @StarlarkBuiltin(name = "MockClassE", doc = "MockClassE")
+  @StarlarkBuiltin(name = "MockClassE", category = DocCategory.BUILTIN, doc = "MockClassE")
   private static class MockClassE extends MockClassA {
     @Override
     public Integer get() {
@@ -150,7 +139,7 @@ public Integer get() {
   }
 
   /** MockClassF */
-  @StarlarkBuiltin(name = "MockClassF", doc = "MockClassF")
+  @StarlarkBuiltin(name = "MockClassF", category = DocCategory.BUILTIN, doc = "MockClassF")
   private static class MockClassF implements StarlarkValue {
     @StarlarkMethod(
         name = "test",
@@ -168,7 +157,7 @@ public Integer test(int a, int b, int c, int d, Sequence args) {
   }
 
   /** MockClassG */
-  @StarlarkBuiltin(name = "MockClassG", doc = "MockClassG")
+  @StarlarkBuiltin(name = "MockClassG", category = DocCategory.BUILTIN, doc = "MockClassG")
   private static class MockClassG implements StarlarkValue {
     @StarlarkMethod(
         name = "test",
@@ -186,7 +175,7 @@ public Integer test(int a, int b, int c, int d, Dict kwargs) {
   }
 
   /** MockClassH */
-  @StarlarkBuiltin(name = "MockClassH", doc = "MockClassH")
+  @StarlarkBuiltin(name = "MockClassH", category = DocCategory.BUILTIN, doc = "MockClassH")
   private static class MockClassH implements StarlarkValue {
     @StarlarkMethod(
         name = "test",
@@ -205,7 +194,7 @@ public Integer test(int a, int b, int c, int d, Sequence args, Dict kwa
   }
 
   /** MockClassI */
-  @StarlarkBuiltin(name = "MockClassI", doc = "MockClassI")
+  @StarlarkBuiltin(name = "MockClassI", category = DocCategory.BUILTIN, doc = "MockClassI")
   private static class MockClassI implements StarlarkValue {
     @StarlarkMethod(
         name = "test",
@@ -255,6 +244,7 @@ public Integer test(int a, int b, int c, int d, Sequence args, Dict kwa
   /** MockClassWithContainerReturnValues */
   @StarlarkBuiltin(
       name = "MockClassWithContainerReturnValues",
+      category = DocCategory.BUILTIN,
       doc = "MockClassWithContainerReturnValues")
   private static class MockClassWithContainerReturnValues implements StarlarkValue {
 
@@ -285,7 +275,10 @@ public Sequence getStarlarkList() {
   }
 
   /** MockClassCommonNameOne */
-  @StarlarkBuiltin(name = "MockClassCommonName", doc = "MockClassCommonName")
+  @StarlarkBuiltin(
+      name = "MockClassCommonName",
+      category = DocCategory.BUILTIN,
+      doc = "MockClassCommonName")
   private static class MockClassCommonNameOne implements StarlarkValue {
 
     @StarlarkMethod(name = "one", doc = "one")
@@ -295,7 +288,10 @@ public Integer one() {
   }
 
   /** SubclassOfMockClassCommonNameOne */
-  @StarlarkBuiltin(name = "MockClassCommonName", doc = "MockClassCommonName")
+  @StarlarkBuiltin(
+      name = "MockClassCommonName",
+      category = DocCategory.BUILTIN,
+      doc = "MockClassCommonName")
   private static class SubclassOfMockClassCommonNameOne extends MockClassCommonNameOne {
 
     @StarlarkMethod(name = "two", doc = "two")
@@ -307,6 +303,7 @@ public Integer two() {
   /** PointsToCommonNameOneWithSubclass */
   @StarlarkBuiltin(
       name = "PointsToCommonNameOneWithSubclass",
+      category = DocCategory.BUILTIN,
       doc = "PointsToCommonNameOneWithSubclass")
   private static class PointsToCommonNameOneWithSubclass implements StarlarkValue {
     @StarlarkMethod(name = "one", doc = "one")
@@ -333,6 +330,7 @@ public Integer two() {
   /** PointsToCommonNameAndUndocumentedModule */
   @StarlarkBuiltin(
       name = "PointsToCommonNameAndUndocumentedModule",
+      category = DocCategory.BUILTIN,
       doc = "PointsToCommonNameAndUndocumentedModule")
   private static class PointsToCommonNameAndUndocumentedModule implements StarlarkValue {
     @StarlarkMethod(name = "one", doc = "one")
@@ -349,6 +347,7 @@ public MockClassCommonNameUndocumented getUndocumented() {
   /** A module which has a selfCall method which constructs copies of MockClassA. */
   @StarlarkBuiltin(
       name = "MockClassWithSelfCallConstructor",
+      category = DocCategory.BUILTIN,
       doc = "MockClassWithSelfCallConstructor")
   private static class MockClassWithSelfCallConstructor implements StarlarkValue {
     @StarlarkMethod(name = "one", doc = "one")
@@ -365,83 +364,93 @@ public MockClassA makeMockClassA() {
 
   @Test
   public void testStarlarkCallableParameters() throws Exception {
-    Map objects = collect(MockClassD.class);
-    StarlarkBuiltinDoc moduleDoc = objects.get("MockClassD");
+    ImmutableMap> objects = collect(MockClassD.class);
+    assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+    StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
     assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassD");
     assertThat(moduleDoc.getMethods()).hasSize(1);
     StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassD#test");
     assertThat(methodDoc.getSignature())
         .isEqualTo(
-            "int MockClassD.test(a, b, *, c, d=1)");
+            "int MockClassD.test(a, b, *, c,"
+                + " d=1)");
     assertThat(methodDoc.getParams()).hasSize(4);
   }
 
   @Test
   public void testStarlarkCallableParametersAndArgs() throws Exception {
-    Map objects = collect(MockClassF.class);
-    StarlarkBuiltinDoc moduleDoc = objects.get("MockClassF");
+    ImmutableMap> objects = collect(MockClassF.class);
+    assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+    StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
     assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassF");
     assertThat(moduleDoc.getMethods()).hasSize(1);
     StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassF#test");
     assertThat(methodDoc.getSignature())
         .isEqualTo(
-            "int "
+            "int "
                 + "MockClassF.test(a, b, *, c, d=1, *myArgs)");
     assertThat(methodDoc.getParams()).hasSize(5);
   }
 
   @Test
   public void testStarlarkCallableParametersAndKwargs() throws Exception {
-    Map objects = collect(MockClassG.class);
-    StarlarkBuiltinDoc moduleDoc = objects.get("MockClassG");
+    ImmutableMap> objects = collect(MockClassG.class);
+    assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+    StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
     assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassG");
     assertThat(moduleDoc.getMethods()).hasSize(1);
     StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassG#test");
     assertThat(methodDoc.getSignature())
         .isEqualTo(
-            "int "
+            "int "
                 + "MockClassG.test(a, b, *, c, d=1, **myKwargs)");
     assertThat(methodDoc.getParams()).hasSize(5);
   }
 
   @Test
   public void testStarlarkCallableParametersAndArgsAndKwargs() throws Exception {
-    Map objects = collect(MockClassH.class);
-    StarlarkBuiltinDoc moduleDoc = objects.get("MockClassH");
+    ImmutableMap> objects = collect(MockClassH.class);
+    assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+    StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
     assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassH");
     assertThat(moduleDoc.getMethods()).hasSize(1);
     StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassH#test");
     assertThat(methodDoc.getSignature())
         .isEqualTo(
-            "int "
+            "int "
                 + "MockClassH.test(a, b, *, c, d=1, *myArgs, **myKwargs)");
     assertThat(methodDoc.getParams()).hasSize(6);
   }
 
   @Test
   public void testStarlarkUndocumentedParameters() throws Exception {
-    Map objects = collect(MockClassI.class);
-    StarlarkBuiltinDoc moduleDoc = objects.get("MockClassI");
+    ImmutableMap> objects = collect(MockClassI.class);
+    assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+    StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
     assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassI");
     assertThat(moduleDoc.getMethods()).hasSize(1);
     StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassI#test");
     assertThat(methodDoc.getSignature())
         .isEqualTo(
-            "int "
+            "int "
                 + "MockClassI.test(a, b, *, c, d=1, *myArgs)");
     assertThat(methodDoc.getParams()).hasSize(5);
   }
 
   @Test
   public void testStarlarkGlobalLibraryCallable() throws Exception {
-    StarlarkBuiltinDoc topLevel =
-        StarlarkDocumentationCollector.getAllModules(expander)
-            .get(StarlarkDocumentationCollector.getTopLevelModule().name());
+    StarlarkDocPage topLevel =
+        StarlarkDocumentationCollector.getAllDocPages(expander)
+            .get(Category.GLOBAL_FUNCTION)
+            .stream()
+            .filter(p -> p.getTitle().equals(Environment.BZL.getTitle()))
+            .findAny()
+            .get();
 
     boolean foundGlobalLibrary = false;
     for (StarlarkMethodDoc methodDoc : topLevel.getMethods()) {
@@ -449,7 +458,7 @@ public void testStarlarkGlobalLibraryCallable() throws Exception {
         assertThat(methodDoc.getDocumentation()).isEqualTo("GlobalCallable documentation");
         assertThat(methodDoc.getSignature())
             .isEqualTo(
-                "int "
+                "int "
                     + "MockGlobalCallable(a, b, *, c, d=1, *myArgs, **myKwargs)");
         foundGlobalLibrary = true;
         break;
@@ -460,84 +469,98 @@ public void testStarlarkGlobalLibraryCallable() throws Exception {
 
   @Test
   public void testStarlarkCallableOverriding() throws Exception {
-    Map objects =
-        collect(ImmutableList.of(MockClassA.class, MockClassE.class));
-    StarlarkBuiltinDoc moduleDoc = objects.get("MockClassE");
+    ImmutableMap> objects =
+        collect(MockClassA.class, MockClassE.class);
+    StarlarkDocPage moduleDoc =
+        objects.get(Category.BUILTIN).stream()
+            .filter(p -> p.getTitle().equals("MockClassE"))
+            .findAny()
+            .get();
     assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassE");
     assertThat(moduleDoc.getMethods()).hasSize(1);
     StarlarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassA#get");
     assertThat(methodDoc.getSignature())
-        .isEqualTo("int MockClassE.get()");
+        .isEqualTo("int MockClassE.get()");
   }
 
   @Test
   public void testStarlarkContainerReturnTypesWithoutAnnotations() throws Exception {
-    Map objects = collect(MockClassWithContainerReturnValues.class);
-    assertThat(objects).containsKey("MockClassWithContainerReturnValues");
-    Collection methods =
-        objects.get("MockClassWithContainerReturnValues").getMethods();
+    ImmutableMap> objects =
+        collect(MockClassWithContainerReturnValues.class);
+    assertThat(objects.get(Category.BUILTIN)).hasSize(1);
+    StarlarkDocPage moduleDoc = objects.get(Category.BUILTIN).get(0);
+    Collection methods = moduleDoc.getMethods();
 
     List signatures =
         methods.stream().map(m -> m.getSignature()).collect(Collectors.toList());
     assertThat(signatures).hasSize(5);
     assertThat(signatures)
         .contains(
-            "depset "
+            "depset "
                 + "MockClassWithContainerReturnValues.depset()");
     assertThat(signatures)
         .contains(
-            "tuple "
+            "tuple "
                 + "MockClassWithContainerReturnValues.tuple()");
     assertThat(signatures)
         .contains(
-            "list "
+            "list "
                 + "MockClassWithContainerReturnValues.immutable()");
     assertThat(signatures)
         .contains(
-            "list "
+            "list "
                 + "MockClassWithContainerReturnValues.mutable()");
     assertThat(signatures)
         .contains(
-            "sequence "
+            "sequence "
                 + "MockClassWithContainerReturnValues.starlark()");
   }
 
   @Test
   public void testDocumentedModuleTakesPrecedence() throws Exception {
-    Map objects =
+    ImmutableMap> objects =
         collect(
-            ImmutableList.of(
-                PointsToCommonNameAndUndocumentedModule.class,
-                MockClassCommonNameOne.class,
-                MockClassCommonNameUndocumented.class));
+            PointsToCommonNameAndUndocumentedModule.class,
+            MockClassCommonNameOne.class,
+            MockClassCommonNameUndocumented.class);
     Collection methods =
-        objects.get("MockClassCommonName").getMethods();
-    List methodNames =
-        methods.stream().map(m -> m.getName()).collect(Collectors.toList());
+        objects.get(Category.BUILTIN).stream()
+            .filter(p -> p.getTitle().equals("MockClassCommonName"))
+            .findAny()
+            .get()
+            .getMethods();
+    List methodNames = methods.stream().map(m -> m.getName()).collect(Collectors.toList());
     assertThat(methodNames).containsExactly("one");
   }
 
   @Test
   public void testDocumentModuleSubclass() {
-    Map objects =
+    ImmutableMap> objects =
         collect(
-            ImmutableList.of(
-                PointsToCommonNameOneWithSubclass.class,
-                MockClassCommonNameOne.class,
-                SubclassOfMockClassCommonNameOne.class));
+            PointsToCommonNameOneWithSubclass.class,
+            MockClassCommonNameOne.class,
+            SubclassOfMockClassCommonNameOne.class);
     Collection methods =
-        objects.get("MockClassCommonName").getMethods();
-    List methodNames =
-        methods.stream().map(m -> m.getName()).collect(Collectors.toList());
+        objects.get(Category.BUILTIN).stream()
+            .filter(p -> p.getTitle().equals("MockClassCommonName"))
+            .findAny()
+            .get()
+            .getMethods();
+    List methodNames = methods.stream().map(m -> m.getName()).collect(Collectors.toList());
     assertThat(methodNames).containsExactly("one", "two");
   }
 
   @Test
   public void testDocumentSelfcallConstructor() {
-    Map objects =
-        collect(ImmutableList.of(MockClassA.class, MockClassWithSelfCallConstructor.class));
-    Collection methods = objects.get("MockClassA").getMethods();
+    ImmutableMap> objects =
+        collect(MockClassA.class, MockClassWithSelfCallConstructor.class);
+    Collection methods =
+        objects.get(Category.BUILTIN).stream()
+            .filter(p -> p.getTitle().equals("MockClassA"))
+            .findAny()
+            .get()
+            .getMethods();
     StarlarkMethodDoc firstMethod = methods.iterator().next();
     assertThat(firstMethod).isInstanceOf(StarlarkConstructorMethodDoc.class);
 
@@ -545,11 +568,8 @@ public void testDocumentSelfcallConstructor() {
     assertThat(methodNames).containsExactly("MockClassA", "get");
   }
 
-  private Map collect(Iterable> classObjects) {
-    return StarlarkDocumentationCollector.collectModules(classObjects, expander);
-  }
-
-  private Map collect(Class classObject) {
-    return collect(ImmutableList.of(classObject));
+  private ImmutableMap> collect(Class... classObjects) {
+    return StarlarkDocumentationCollector.collectDocPages(
+        ImmutableList.copyOf(classObjects), expander);
   }
 }