Rename @DocumentMethods to @GlobalMethods and add "environment" infor…

…mation

- Renamed to emphasize the fact that each method in there is available as a global method (aka top-level binding).
- Added a mandatory "environment" field to let classes specify in which environment their methods are supposed to be available: BUILD files, WORKSPACE files, MODULE files, or .bzl files.
  - This information will be used in a follow-up CL.

Work towards bazelbuild#16383

PiperOrigin-RevId: 522080811
Change-Id: I94bb50011147cee30a141b002e968a323c40a1be

src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java

@@ -17,7 +17,7 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Iterables;
 import com.google.devtools.build.docgen.annot.DocCategory;
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods;
 import com.google.devtools.build.docgen.annot.StarlarkConstructor;
 import com.google.devtools.build.docgen.starlark.StarlarkBuiltinDoc;
 import com.google.devtools.build.docgen.starlark.StarlarkConstructorMethodDoc;
@@ -115,7 +115,7 @@ static ImmutableMap<String, StarlarkBuiltinDoc> collectModules(
       if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)) {
         collectModuleMethods(candidateClass, modules, expander);
       }
-      if (candidateClass.isAnnotationPresent(DocumentMethods.class)
+      if (candidateClass.isAnnotationPresent(GlobalMethods.class)
           || candidateClass.getName().equals("net.starlark.java.eval.MethodLibrary")) {
         collectDocumentedMethods(candidateClass, modules, expander);
       }
@@ -124,7 +124,7 @@ static ImmutableMap<String, StarlarkBuiltinDoc> collectModules(
     // 3. Add all constructors.
     for (Class<?> candidateClass : classes) {
       if (candidateClass.isAnnotationPresent(StarlarkBuiltin.class)
-          || candidateClass.isAnnotationPresent(DocumentMethods.class)) {
+          || candidateClass.isAnnotationPresent(GlobalMethods.class)) {
         collectConstructorMethods(candidateClass, modules, expander);
       }
     }
@@ -250,7 +250,7 @@ private static Method getSelfCallConstructorMethod(Class<?> objectClass) {
 
   /**
    * Adds {@link StarlarkJavaMethodDoc} entries to the top level module, one for
-   * each @StarlarkMethod method defined in the given @DocumentMethods class {@code moduleClass}.
+   * each @StarlarkMethod method defined in the given @GlobalMethods class {@code moduleClass}.
    */
   private static void collectDocumentedMethods(
       Class<?> moduleClass, Map<String, StarlarkBuiltinDoc> modules, StarlarkDocExpander expander) {

src/main/java/com/google/devtools/build/docgen/annot/BUILD

@@ -15,7 +15,8 @@ java_library(
     name = "annot",
     srcs = [
         "DocCategory.java",
-        "DocumentMethods.java",
+        "GlobalMethods.java",
         "StarlarkConstructor.java",
     ],
+    deps = ["//third_party:guava"],
 )

src/main/java/com/google/devtools/build/docgen/annot/DocumentMethods.java → src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java

@@ -13,20 +13,42 @@
 // limitations under the License.
 package com.google.devtools.build.docgen.annot;
 
+import com.google.common.base.Ascii;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * A annotation applied to a class that indicates to docgen that the class's {@link
+ * An annotation applied to a class that indicates to docgen that the class's {@link
  * net.starlark.java.annot.StarlarkMethod}-annotated methods should be included in docgen's output
- * as standalone functions.
- *
- * <p>It is not necessary to apply this annotation to a class already annotated with {@link
- * net.starlark.java.annot.StarlarkBuiltin}; docgen will automatically document such classes as
- * built-in data types with Starlark methods defined by the annotated Java methods.
+ * as standalone global functions.
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
-public @interface DocumentMethods {}
+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");
+
+    private final String title;
+
+    Environment(String title) {
+      this.title = title;
+    }
+
+    public String getTitle() {
+      return title;
+    }
+
+    public String getPath() {
+      return Ascii.toLowerCase(name());
+    }
+  }
+
+  Environment[] environment();
+}

src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleFileGlobals.java

@@ -24,7 +24,8 @@
 import com.google.common.collect.ImmutableCollection;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
 import com.google.devtools.build.lib.bazel.bzlmod.ModuleFileGlobals.ModuleExtensionUsageBuilder.ModuleExtensionProxy;
 import com.google.devtools.build.lib.bazel.bzlmod.Version.ParseException;
 import com.google.devtools.build.lib.cmdline.RepositoryName;
@@ -51,7 +52,7 @@
 import net.starlark.java.syntax.Location;
 
 /** A collection of global Starlark build API functions that apply to MODULE.bazel files. */
-@DocumentMethods
+@GlobalMethods(environment = Environment.MODULE)
 public class ModuleFileGlobals {
 
   /* Valid bazel compatibility argument must 1) start with (<,<=,>,>=,-);

src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java

@@ -22,7 +22,8 @@
 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.DocumentMethods;
+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;
@@ -65,7 +66,7 @@
  * The Starlark module containing the definition of {@code repository_rule} function to define a
  * Starlark remote repository.
  */
-@DocumentMethods
+@GlobalMethods(environment = Environment.BZL)
 public class StarlarkRepositoryModule implements RepositoryModuleApi {
 
   @Override

src/main/java/com/google/devtools/build/lib/packages/StarlarkLibrary.java

@@ -17,7 +17,8 @@
 
 import com.google.common.collect.ImmutableMap;
 import com.google.devtools.build.docgen.annot.DocCategory;
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+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 com.google.devtools.build.lib.cmdline.LabelSyntaxException;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
@@ -260,7 +261,7 @@ private void emitLine(String... items) {
     }
   }
 
-  @DocumentMethods
+  @GlobalMethods(environment = {Environment.BUILD, Environment.BZL})
   private static final class DepsetLibrary {
     @StarlarkMethod(
         name = "depset",
@@ -333,7 +334,7 @@ public Depset depset(
   }
 
   /** A starlark library supporting Bazel's implementation of the `select()` Starlark function. */
-  @DocumentMethods
+  @GlobalMethods(environment = {Environment.BUILD, Environment.BZL})
   public static final class SelectLibrary {
     @StarlarkMethod(
         name = "select",
@@ -378,7 +379,7 @@ private static ImmutableMap<String, Object> initBUILD() {
     return env.buildOrThrow();
   }
 
-  @DocumentMethods
+  @GlobalMethods(environment = Environment.BUILD)
   private static class BuildLibrary {
     @StarlarkMethod(
         name = "environment_group",

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkBuildApiGlobals.java

@@ -14,14 +14,15 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi;
 
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.StarlarkMethod;
 import net.starlark.java.eval.EvalException;
 import net.starlark.java.eval.StarlarkThread;
 
 /** A collection of global Starlark build API functions that belong in the global namespace. */
-@DocumentMethods
+@GlobalMethods(environment = Environment.BZL)
 public interface StarlarkBuildApiGlobals {
 
   @StarlarkMethod(

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java

@@ -14,7 +14,8 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi;
 
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+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.lib.cmdline.Label;
 import com.google.devtools.build.lib.packages.semantics.BuildLanguageOptions;
@@ -34,7 +35,7 @@
  * Interface for a global Starlark library containing rule-related helper and registration
  * functions.
  */
-@DocumentMethods
+@GlobalMethods(environment = Environment.BZL)
 public interface StarlarkRuleFunctionsApi<FileApiT extends FileApi> {
 
   String EXEC_COMPATIBLE_WITH_PARAM = "exec_compatible_with";

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/WorkspaceGlobalsApi.java

@@ -15,7 +15,8 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi;
 
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.ParamType;
 import net.starlark.java.annot.StarlarkMethod;
@@ -25,7 +26,7 @@
 import net.starlark.java.eval.StarlarkThread;
 
 /** A collection of global Starlark build API functions that apply to WORKSPACE files. */
-@DocumentMethods
+@GlobalMethods(environment = Environment.WORKSPACE)
 public interface WorkspaceGlobalsApi {
 
   @StarlarkMethod(

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/config/ConfigGlobalLibraryApi.java

@@ -14,7 +14,8 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi.config;
 
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+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 net.starlark.java.annot.Param;
 import net.starlark.java.annot.ParamType;
@@ -26,7 +27,7 @@
 import net.starlark.java.eval.StarlarkThread;
 
 /** A collection of top-level Starlark functions pertaining to configuration. */
-@DocumentMethods
+@GlobalMethods(environment = Environment.BZL)
 public interface ConfigGlobalLibraryApi {
   @StarlarkMethod(
       name = "transition",

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java

@@ -14,7 +14,8 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi.repository;
 
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+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;
@@ -30,7 +31,7 @@
  * The Starlark module containing the definition of {@code repository_rule} function to define a
  * Starlark remote repository.
  */
-@DocumentMethods
+@GlobalMethods(environment = Environment.BZL)
 public interface RepositoryModuleApi {
 
   @StarlarkMethod(

src/test/java/com/google/devtools/build/docgen/StarlarkDocumentationTest.java

@@ -18,7 +18,8 @@
 
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
-import com.google.devtools.build.docgen.annot.DocumentMethods;
+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;
@@ -232,7 +233,7 @@ public Integer test(int a, int b, int c, int d, int e, Sequence<?> args) {
    * StarlarkDocumentationTest checks all of the classes under a wide classpath and ensures this one
    * shows up.
    */
-  @DocumentMethods
+  @GlobalMethods(environment = Environment.BZL)
   @SuppressWarnings("unused")
   private static class MockGlobalLibrary {
     @StarlarkMethod(