From 99a818630ed51b010d2b8bba705a06fa759450d3 Mon Sep 17 00:00:00 2001 From: Googler Date: Wed, 9 Nov 2022 05:01:42 -0800 Subject: [PATCH] Fix missing DocCategory values causing symbols to show up in wrong places If the `category` field of the `@StarlarkBuiltin` annotation is not specified, it defaults to a "top-level module" category, which is often not correct. For example, in `attr.label(...)`, `attr` is a top-level module; but most of the things currently listed as top-level modules are not; instead, they should be listed as built-in types. This CL does just that. PiperOrigin-RevId: 487211322 Change-Id: Ide6739e96e395b0bda6cd71b07e02590b0bb488c --- .../build/docgen/StarlarkDocumentationCollector.java | 6 +++--- .../java/com/google/devtools/build/lib/bazel/bzlmod/BUILD | 1 + .../devtools/build/lib/bazel/bzlmod/ModuleExtension.java | 6 +++++- .../build/lib/bazel/bzlmod/StarlarkBazelModule.java | 3 +++ .../google/devtools/build/lib/bazel/bzlmod/TagClass.java | 6 +++++- .../devtools/build/lib/bazel/bzlmod/TypeCheckedTag.java | 2 +- .../build/lib/starlarkbuildapi/TemplateDictApi.java | 2 +- .../starlarkbuildapi/test/AnalysisTestResultInfoApi.java | 2 ++ 8 files changed, 21 insertions(+), 7 deletions(-) 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 188fb6fdfb07e5..433016dd63c441 100644 --- a/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java +++ b/src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java @@ -60,9 +60,9 @@ static synchronized ImmutableMap getAllModules( all = collectModules( Iterables.concat( - Classpath.findClasses("com/google/devtools/build"), // Bazel - Classpath.findClasses("net/starlark/java")), - expander); // Starlark + /*Bazel*/ Classpath.findClasses("com/google/devtools/build"), + /*Starlark*/ Classpath.findClasses("net/starlark/java")), + expander); } return all; } diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/BUILD b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/BUILD index a3a3a5fe760ee8..a20cc3d8d7609c 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/BUILD +++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/BUILD @@ -49,6 +49,7 @@ java_library( "TagClass.java", ], deps = [ + "//src/main/java/com/google/devtools/build/docgen/annot", "//src/main/java/com/google/devtools/build/lib/cmdline", "//src/main/java/com/google/devtools/build/lib/events", "//src/main/java/com/google/devtools/build/lib/packages", diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java index a55de9583b2545..b9d2ffd6a98337 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java @@ -17,6 +17,7 @@ import com.google.auto.value.AutoValue; import com.google.common.base.Preconditions; import com.google.common.collect.ImmutableMap; +import com.google.devtools.build.docgen.annot.DocCategory; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.build.lib.events.EventHandler; import com.google.devtools.build.lib.packages.StarlarkExportable; @@ -72,7 +73,10 @@ public abstract static class Builder { * it's exported, at which point it sets the name and builds the underlying {@link * ModuleExtension}. */ - @StarlarkBuiltin(name = "module_extension", doc = "A module extension.") + @StarlarkBuiltin( + name = "module_extension", + category = DocCategory.BUILTIN, + doc = "A module extension declared using the module_extension function.") public static class InStarlark implements StarlarkExportable { private final Builder builder; @Nullable private ModuleExtension built; diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java index 7491a9ea449211..934314f65b46d7 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/StarlarkBazelModule.java @@ -18,6 +18,7 @@ import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.common.collect.Maps; +import com.google.devtools.build.docgen.annot.DocCategory; import com.google.devtools.build.lib.cmdline.PackageIdentifier; import com.google.devtools.build.lib.cmdline.RepositoryMapping; import com.google.devtools.build.lib.packages.LabelConverter; @@ -37,6 +38,7 @@ /** A Starlark object representing a Bazel module in the external dependency graph. */ @StarlarkBuiltin( name = "bazel_module", + category = DocCategory.BUILTIN, doc = "Represents a Bazel module in the external dependency graph.") public class StarlarkBazelModule implements StarlarkValue { private final String name; @@ -46,6 +48,7 @@ public class StarlarkBazelModule implements StarlarkValue { @StarlarkBuiltin( name = "bazel_module_tags", + category = DocCategory.BUILTIN, doc = "Contains the tags in a module for the module extension currently being processed. This" + " object has a field for each tag class of the extension, and the value of the" diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TagClass.java b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TagClass.java index f2bdc7c1e93e8d..7c6f8030103d61 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TagClass.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TagClass.java @@ -17,6 +17,7 @@ import com.google.auto.value.AutoValue; 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.lib.packages.Attribute; import net.starlark.java.annot.StarlarkBuiltin; import net.starlark.java.eval.StarlarkValue; @@ -25,7 +26,10 @@ /** * Represents a tag class, which is a "class" of {@link Tag}s that share the same attribute schema. */ -@StarlarkBuiltin(name = "tag_class", doc = "Defines a schema of attributes for a tag.") +@StarlarkBuiltin( + name = "tag_class", + category = DocCategory.BUILTIN, + doc = "Defines a schema of attributes for a tag.") @AutoValue public abstract class TagClass implements StarlarkValue { /** The list of attributes of this tag class. */ diff --git a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TypeCheckedTag.java b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TypeCheckedTag.java index 4ef93352ccc619..855c8cb465a5b1 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TypeCheckedTag.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TypeCheckedTag.java @@ -29,7 +29,7 @@ * A {@link Tag} whose attribute values have been type-checked against the attribute schema define * in the {@link TagClass}. */ -@StarlarkBuiltin(name = "bazel_module_tag", doc = "TODO") +@StarlarkBuiltin(name = "bazel_module_tag", documented = false) public class TypeCheckedTag implements Structure { private final TagClass tagClass; private final Object[] attrValues; 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 39c648d3b84613..48389d50359af6 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 @@ -27,7 +27,7 @@ /** Template expansion dict module. */ @StarlarkBuiltin( name = "TemplateDict", - category = DocCategory.TOP_LEVEL_TYPE, + category = DocCategory.BUILTIN, doc = "An Args-like structure for use in ctx.actions.expand_template(), which allows for" + " deferring evaluation of values till the execution phase.") diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java index a90f3704a48137..6089f41dad2011 100644 --- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java +++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/test/AnalysisTestResultInfoApi.java @@ -14,6 +14,7 @@ package com.google.devtools.build.lib.starlarkbuildapi.test; +import com.google.devtools.build.docgen.annot.DocCategory; import com.google.devtools.build.docgen.annot.StarlarkConstructor; import com.google.devtools.build.lib.starlarkbuildapi.core.ProviderApi; import net.starlark.java.annot.Param; @@ -26,6 +27,7 @@ */ @StarlarkBuiltin( name = "AnalysisTestResultInfo", + category = DocCategory.PROVIDER, doc = "Encapsulates the result of analyis-phase testing. Build targets which return an instance" + " of this provider signal to the build system that it should generate a 'stub' test"