From 7dbd645c09f684015c280f260443dfd6f6eba478 Mon Sep 17 00:00:00 2001 From: Googler Date: Tue, 11 Apr 2023 03:42:41 -0700 Subject: [PATCH] Prevent repository_rule from showing up twice in documentation - Removed @GlobalMethods from StarlarkRepositoryModule as the interface RepositoryModuleApi is already annotated with @GlobalMethods - Moved the two methods, `moduleExtension` and `tagClass`, and their documentation, to the interface instead - Added no-op fake implementation for the two methods in FakeRepositoryModule - TagClass's documentation is moved to an interface RepositoryModuleApi.TagClassApi (so that we can still refer to it); ModuleExtension's documentation is removed, as that type is never meaningfully used in Starlark (only exported) Work towards https://github.com/bazelbuild/bazel/issues/16383 PiperOrigin-RevId: 523356118 Change-Id: Ic937be3c41bcf7d748945d7bc2d2afb124d9c4bd --- .../devtools/build/lib/bazel/bzlmod/BUILD | 3 +- .../lib/bazel/bzlmod/ModuleExtension.java | 6 -- .../build/lib/bazel/bzlmod/TagClass.java | 10 +-- .../build/lib/bazel/repository/starlark/BUILD | 1 + .../starlark/StarlarkRepositoryModule.java | 66 +-------------- .../repository/RepositoryModuleApi.java | 80 +++++++++++++++++++ .../repository/FakeRepositoryModule.java | 13 +++ 7 files changed, 100 insertions(+), 79 deletions(-) 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 afb981497c796e..be8f1938dd6884 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 @@ -51,10 +51,9 @@ 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/packages", - "//src/main/java/net/starlark/java/annot", + "//src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository", "//src/main/java/net/starlark/java/eval", "//src/main/java/net/starlark/java/syntax", "//third_party:auto_value", 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 9ba37a4ebc43ce..8bd528a3969971 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 @@ -16,8 +16,6 @@ import com.google.auto.value.AutoValue; import com.google.common.collect.ImmutableMap; -import com.google.devtools.build.docgen.annot.DocCategory; -import net.starlark.java.annot.StarlarkBuiltin; import net.starlark.java.eval.StarlarkCallable; import net.starlark.java.eval.StarlarkValue; import net.starlark.java.syntax.Location; @@ -26,10 +24,6 @@ * A module extension object, which can be used to perform arbitrary logic in order to create repos. */ @AutoValue -@StarlarkBuiltin( - name = "module_extension", - category = DocCategory.BUILTIN, - doc = "A module extension declared using the module_extension function.") public abstract class ModuleExtension implements StarlarkValue { public abstract StarlarkCallable getImplementation(); 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 7c6f8030103d61..fbc3b8d83313d0 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,21 +17,15 @@ 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; +import com.google.devtools.build.lib.starlarkbuildapi.repository.RepositoryModuleApi.TagClassApi; import net.starlark.java.syntax.Location; /** * Represents a tag class, which is a "class" of {@link Tag}s that share the same attribute schema. */ -@StarlarkBuiltin( - name = "tag_class", - category = DocCategory.BUILTIN, - doc = "Defines a schema of attributes for a tag.") @AutoValue -public abstract class TagClass implements StarlarkValue { +public abstract class TagClass implements TagClassApi { /** The list of attributes of this tag class. */ public abstract ImmutableList getAttributes(); diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/BUILD b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/BUILD index e198fd737fc2f4..51564c20b36ee8 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/BUILD +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/BUILD @@ -55,6 +55,7 @@ java_library( "//src/main/java/net/starlark/java/annot", "//src/main/java/net/starlark/java/eval", "//src/main/java/net/starlark/java/syntax", + "//third_party:error_prone_annotations", "//third_party:guava", "//third_party:java-diff-utils", "//third_party:jsr305", diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java index 3c1a47c17d964a..cf1b9199f6b819 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java @@ -22,8 +22,6 @@ 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.annot.GlobalMethods; -import com.google.devtools.build.docgen.annot.GlobalMethods.Environment; import com.google.devtools.build.lib.analysis.BaseRuleClasses; import com.google.devtools.build.lib.analysis.starlark.StarlarkAttrModule.Descriptor; import com.google.devtools.build.lib.bazel.bzlmod.ModuleExtension; @@ -49,9 +47,7 @@ import com.google.devtools.build.lib.packages.semantics.BuildLanguageOptions; import com.google.devtools.build.lib.starlarkbuildapi.repository.RepositoryModuleApi; import java.util.Map; -import net.starlark.java.annot.Param; import net.starlark.java.annot.StarlarkBuiltin; -import net.starlark.java.annot.StarlarkMethod; import net.starlark.java.eval.Dict; import net.starlark.java.eval.EvalException; import net.starlark.java.eval.Module; @@ -66,7 +62,6 @@ * The Starlark module containing the definition of {@code repository_rule} function to define a * Starlark remote repository. */ -@GlobalMethods(environment = Environment.BZL) public class StarlarkRepositoryModule implements RepositoryModuleApi { @Override @@ -260,40 +255,8 @@ public void failWithIncompatibleUseCcConfigureFromRulesCc(StarlarkThread thread) } } - @StarlarkMethod( - name = "module_extension", - doc = - "Creates a new module extension. Store it in a global value, so that it can be exported" - + " and used in a MODULE.bazel file.", - parameters = { - @Param( - name = "implementation", - 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."), - @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.", - named = true, - positional = false), - @Param( - name = "doc", - defaultValue = "''", - doc = - "A description of the module extension that can be extracted by documentation" - + " generating tools.", - named = true, - positional = false) - }, - useStarlarkThread = true) - public ModuleExtension moduleExtension( + @Override + public Object moduleExtension( StarlarkCallable implementation, Dict tagClasses, // Dict String doc, @@ -308,30 +271,7 @@ public ModuleExtension moduleExtension( .build(); } - @StarlarkMethod( - name = "tag_class", - doc = - "Creates a new tag_class object, which defines an attribute schema for a class of tags," - + " which are data objects usable by a module extension.", - parameters = { - @Param( - name = "attrs", - defaultValue = "{}", - 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)."), - @Param( - name = "doc", - defaultValue = "''", - doc = - "A description of the tag class that can be extracted by documentation" - + " generating tools.", - named = true, - positional = false) - }, - useStarlarkThread = true) + @Override public TagClass tagClass( Dict attrs, // Dict String doc, 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 3a9c68354b52cb..d1ad2dc04f4d03 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 @@ -14,11 +14,13 @@ package com.google.devtools.build.lib.starlarkbuildapi.repository; +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.packages.semantics.BuildLanguageOptions; import net.starlark.java.annot.Param; import net.starlark.java.annot.ParamType; +import net.starlark.java.annot.StarlarkBuiltin; import net.starlark.java.annot.StarlarkMethod; import net.starlark.java.eval.Dict; import net.starlark.java.eval.EvalException; @@ -26,6 +28,7 @@ import net.starlark.java.eval.Sequence; import net.starlark.java.eval.StarlarkCallable; import net.starlark.java.eval.StarlarkThread; +import net.starlark.java.eval.StarlarkValue; /** * The Starlark module containing the definition of {@code repository_rule} function to define a @@ -119,6 +122,83 @@ StarlarkCallable repositoryRule( StarlarkThread thread) throws EvalException; + @StarlarkMethod( + name = "module_extension", + doc = + "Creates a new module extension. Store it in a global value, so that it can be exported" + + " and used in a MODULE.bazel file.", + parameters = { + @Param( + name = "implementation", + 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."), + @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.", + named = true, + positional = false), + @Param( + name = "doc", + defaultValue = "''", + doc = + "A description of the module extension that can be extracted by documentation" + + " generating tools.", + named = true, + positional = false) + }, + useStarlarkThread = true) + Object moduleExtension( + StarlarkCallable implementation, + Dict tagClasses, // Dict + String doc, + StarlarkThread thread) + throws EvalException; + + @StarlarkMethod( + name = "tag_class", + doc = + "Creates a new tag_class object, which defines an attribute schema for a class of tags," + + " which are data objects usable by a module extension.", + parameters = { + @Param( + name = "attrs", + defaultValue = "{}", + 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)."), + @Param( + name = "doc", + defaultValue = "''", + doc = + "A description of the tag class that can be extracted by documentation" + + " generating tools.", + named = true, + positional = false) + }, + useStarlarkThread = true) + TagClassApi tagClass( + Dict attrs, // Dict + String doc, + StarlarkThread thread) + throws EvalException; + + /** Represents a tag class, which is a "class" of tags that share the same attribute schema. */ + @StarlarkBuiltin( + name = "tag_class", + category = DocCategory.BUILTIN, + doc = "Defines a schema of attributes for a tag.") + interface TagClassApi extends StarlarkValue {} + @StarlarkMethod( name = "__do_not_use_fail_with_incompatible_use_cc_configure_from_rules_cc", doc = diff --git a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java index d1478ee7ab6be1..355e77f323c564 100644 --- a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java +++ b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java @@ -122,6 +122,19 @@ public String getName() { } } + @Override + public Object moduleExtension( + StarlarkCallable implementation, Dict tagClasses, String doc, StarlarkThread thread) + throws EvalException { + return new Object(); + } + + @Override + public TagClassApi tagClass(Dict attrs, String doc, StarlarkThread thread) + throws EvalException { + return new TagClassApi() {}; + } + @Override public void failWithIncompatibleUseCcConfigureFromRulesCc(StarlarkThread thread) throws EvalException {