Fix DocCategory usage

- All @StarlarkBuiltin annotations that don't have `documented=false` should have a DocCategory set. This CL fixes offending cases, but doesn't change the annotation processor to enforce it; that can be done later.
- Fixed @StarlarkBuiltin annotations that had the wrong DocCategory.
- Removed DocCategory.NONE; it doesn't mean anything.
- Renamed DocCategory.TOP_LEVEL_TYPE to TOP_LEVEL_MODULE. This category represents stuff like `attr`, which we don't typically think of as "types" (you don't create instances of `attr` the module).

Work towards bazelbuild#16383

PiperOrigin-RevId: 522079755
Change-Id: I969e52939139d7e9d584060dfe0b541f1fd42b23

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

@@ -40,7 +40,7 @@
 final class StarlarkDocumentationCollector {
   @StarlarkBuiltin(
       name = "globals",
-      category = DocCategory.TOP_LEVEL_TYPE,
+      category = DocCategory.TOP_LEVEL_MODULE,
       doc = "Objects, functions and modules registered in the global environment.")
   private static final class TopLevelModule implements StarlarkValue {}
 

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

@@ -36,7 +36,7 @@
 public final class StarlarkDocumentationProcessor {
 
   private static final ImmutableList<Category> GLOBAL_CATEGORIES =
-      ImmutableList.<Category>of(Category.NONE, Category.TOP_LEVEL_TYPE);
+      ImmutableList.of(Category.TOP_LEVEL_MODULE);
 
   private StarlarkDocumentationProcessor() {}
 
@@ -90,7 +90,7 @@ public static void generateDocumentation(String outputDir, String... args)
     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_TYPE));
+    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.
@@ -137,7 +137,7 @@ public static void generateDocumentation(String outputDir, String... args)
 
   private static StarlarkBuiltinDoc findGlobalModule(
       Map<Category, List<StarlarkBuiltinDoc>> modulesByCategory) {
-    List<StarlarkBuiltinDoc> topLevelModules = modulesByCategory.get(Category.TOP_LEVEL_TYPE);
+    List<StarlarkBuiltinDoc> topLevelModules = modulesByCategory.get(Category.TOP_LEVEL_MODULE);
     String globalModuleName = StarlarkDocumentationCollector.getTopLevelModule().name();
     for (StarlarkBuiltinDoc module : topLevelModules) {
       if (module.getName().equals(globalModuleName)) {
@@ -253,16 +253,13 @@ public enum Category {
     // be usable solely by accessing their members, via modulename.funcname() or
     // modulename.constantname.
     // Examples: attr, cc_common, config, java_common
-    TOP_LEVEL_TYPE(null, null),
+    TOP_LEVEL_MODULE(null, null),
 
     CORE(
         "Core Starlark data types",
         "This section lists the data types of the <a"
             + " href='https://github.com/bazelbuild/starlark/blob/master/spec.md#built-in-constants-and-functions'>Starlark"
-            + " core language</a>."),
-
-    // Legacy uncategorized type; these are treated like TOP_LEVEL_TYPE in documentation.
-    NONE(null, null);
+            + " core language</a>.");
 
     // Maps (essentially free-form) strings in annotations to permitted categories.
     static Category of(StarlarkBuiltin annot) {
@@ -273,15 +270,11 @@ static Category of(StarlarkBuiltin annot) {
           return PROVIDER;
         case DocCategory.BUILTIN:
           return BUILTIN;
-        case DocCategory.TOP_LEVEL_TYPE:
-          return TOP_LEVEL_TYPE;
-        case DocCategory.NONE:
-          return NONE;
+        case DocCategory.TOP_LEVEL_MODULE:
+          return TOP_LEVEL_MODULE;
         case "core": // interpreter built-ins (e.g. int)
         case "core.lib": // Starlark standard modules (e.g. json)
           return CORE;
-        case "": // no annotation
-          return TOP_LEVEL_TYPE;
         default:
           throw new IllegalStateException(
               String.format(

src/main/java/com/google/devtools/build/docgen/annot/DocCategory.java

@@ -26,7 +26,5 @@ private DocCategory() {} // uninstantiable
 
   public static final String BUILTIN = "BUILTIN";
 
-  public static final String TOP_LEVEL_TYPE = "TOP_LEVEL_TYPE";
-
-  public static final String NONE = "NONE";
+  public static final String TOP_LEVEL_MODULE = "TOP_LEVEL_MODULE";
 }

src/main/java/com/google/devtools/build/lib/bazel/rules/python/BUILD

@@ -20,18 +20,11 @@ java_library(
         ],
     ),
     deps = [
-        "//src/main/java/com/google/devtools/build/lib/actions",
+        "//src/main/java/com/google/devtools/build/docgen/annot",
         "//src/main/java/com/google/devtools/build/lib/actions:artifacts",
-        "//src/main/java/com/google/devtools/build/lib/actions:commandline_item",
-        "//src/main/java/com/google/devtools/build/lib/analysis:actions/custom_command_line",
-        "//src/main/java/com/google/devtools/build/lib/analysis:actions/launcher_file_write_action",
-        "//src/main/java/com/google/devtools/build/lib/analysis:actions/substitution",
-        "//src/main/java/com/google/devtools/build/lib/analysis:actions/template",
-        "//src/main/java/com/google/devtools/build/lib/analysis:actions/template_expansion_action",
         "//src/main/java/com/google/devtools/build/lib/analysis:analysis_cluster",
         "//src/main/java/com/google/devtools/build/lib/analysis:config/build_options",
         "//src/main/java/com/google/devtools/build/lib/analysis:config/core_option_converters",
-        "//src/main/java/com/google/devtools/build/lib/analysis:config/execution_transition_factory",
         "//src/main/java/com/google/devtools/build/lib/analysis:config/fragment",
         "//src/main/java/com/google/devtools/build/lib/analysis:config/fragment_options",
         "//src/main/java/com/google/devtools/build/lib/analysis:config/invalid_configuration_exception",
@@ -41,17 +34,14 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/analysis/starlark/annotations",
         "//src/main/java/com/google/devtools/build/lib/bazel/rules/cpp",
         "//src/main/java/com/google/devtools/build/lib/cmdline",
-        "//src/main/java/com/google/devtools/build/lib/collect/nestedset",
         "//src/main/java/com/google/devtools/build/lib/concurrent",
         "//src/main/java/com/google/devtools/build/lib/events",
         "//src/main/java/com/google/devtools/build/lib/packages",
         "//src/main/java/com/google/devtools/build/lib/rules/cpp",
         "//src/main/java/com/google/devtools/build/lib/rules/python",
-        "//src/main/java/com/google/devtools/build/lib/util:os",
         "//src/main/java/com/google/devtools/build/lib/vfs:pathfragment",
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/java/net/starlark/java/annot",
         "//third_party:guava",
-        "//third_party:jsr305",
     ],
 )

src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java

@@ -14,6 +14,7 @@
 
 package com.google.devtools.build.lib.bazel.rules.python;
 
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.analysis.config.BuildOptions;
 import com.google.devtools.build.lib.analysis.config.CoreOptionConverters.LabelConverter;
 import com.google.devtools.build.lib.analysis.config.Fragment;
@@ -36,7 +37,7 @@
 
 /** Bazel-specific Python configuration. */
 @Immutable
-@StarlarkBuiltin(name = "bazel_py")
+@StarlarkBuiltin(name = "bazel_py", category = DocCategory.CONFIGURATION_FRAGMENT)
 @RequiresOptions(options = {BazelPythonConfiguration.Options.class, PythonOptions.class})
 public class BazelPythonConfiguration extends Fragment {
 

src/main/java/com/google/devtools/build/lib/rules/cpp/CcLauncherInfo.java

@@ -15,7 +15,6 @@
 package com.google.devtools.build.lib.rules.cpp;
 
 import com.google.common.annotations.VisibleForTesting;
-import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.analysis.RuleContext;
 import com.google.devtools.build.lib.packages.BuiltinProvider;
 import com.google.devtools.build.lib.packages.NativeInfo;
@@ -38,8 +37,7 @@
     documented = false,
     doc =
         "Provider that signals that rules that use launchers can use this target as "
-            + "the launcher.",
-    category = DocCategory.TOP_LEVEL_TYPE)
+            + "the launcher.")
 public class CcLauncherInfo extends NativeInfo {
   private static final String RESTRICTION_ERROR_MESSAGE =
       "This provider is restricted to native.java_binary, native.py_binary and native.java_test. "

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

@@ -38,7 +38,7 @@
  */
 @StarlarkBuiltin(
     name = "attr",
-    category = DocCategory.TOP_LEVEL_TYPE,
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc =
         "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"

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

@@ -25,7 +25,7 @@
 /** Interface for a module associated with creating efficient command lines. */
 @StarlarkBuiltin(
     name = "cmd_helper",
-    category = DocCategory.TOP_LEVEL_TYPE,
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc = "Deprecated. Module for creating memory efficient command lines.")
 public interface StarlarkCommandLineApi extends StarlarkValue {
 

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

@@ -31,7 +31,7 @@
  */
 @StarlarkBuiltin(
     name = "config",
-    category = DocCategory.BUILTIN,
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc =
         "This is a top-level module for creating configuration transitions and build "
             + "setting descriptors which describe what kind of build setting (if any) a rule is. "

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

@@ -31,7 +31,7 @@
 /** Interface for a module with native rule and package helper functions. */
 @StarlarkBuiltin(
     name = "native",
-    category = DocCategory.BUILTIN,
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc =
         "A built-in module to support native rules and other package helper functions. "
             + "All native rules appear as functions in this module, e.g. "

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/android/AndroidNeverLinkLibrariesProviderApi.java

@@ -13,6 +13,7 @@
 // limitations under the License.
 package com.google.devtools.build.lib.starlarkbuildapi.android;
 
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.docgen.annot.StarlarkConstructor;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
 import com.google.devtools.build.lib.starlarkbuildapi.FileApi;
@@ -27,6 +28,7 @@
 /** Provides information about neverlink libraries for Android targets. */
 @StarlarkBuiltin(
     name = "AndroidNeverLinkLibrariesProvider",
+    category = DocCategory.PROVIDER,
     doc = "Information about neverlink libraries for Android targets.")
 public interface AndroidNeverLinkLibrariesProviderApi<FileT extends FileApi> extends StructApi {
 

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/android/AndroidStarlarkApiProviderApi.java

@@ -146,7 +146,6 @@ public interface AndroidStarlarkApiProviderApi<FileT extends FileApi> extends St
   /** Helper class to provide information about IDLs related to this rule. */
   @StarlarkBuiltin(
       name = "AndroidStarlarkIdlInfo",
-      category = DocCategory.NONE,
       doc =
           "Do not use this module. It is intended for migration purposes only. If you depend on "
               + "it, you will be broken when it is removed."

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple/AppleToolchainApi.java

@@ -14,6 +14,7 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi.apple;
 
+import com.google.devtools.build.docgen.annot.DocCategory;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.StarlarkBuiltin;
 import net.starlark.java.annot.StarlarkMethod;
@@ -22,6 +23,7 @@
 /** Interface for a utility module involving the Apple toolchain. */
 @StarlarkBuiltin(
     name = "apple_toolchain",
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc = "Utilities for resolving items from the Apple toolchain.")
 public interface AppleToolchainApi<AppleConfigurationApiT extends AppleConfigurationApi<?>>
     extends StarlarkValue {

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

@@ -14,6 +14,7 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi.config;
 
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.analysis.config.transitions.StarlarkExposedRuleTransitionFactory;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.build.lib.starlarkbuildapi.core.ProviderApi;
@@ -28,6 +29,7 @@
 /** Helper utility containing functions regarding configurations.ss */
 @StarlarkBuiltin(
     name = "config_common",
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc = "Functions for Starlark to interact with Blaze's configurability APIs.")
 public interface ConfigStarlarkCommonApi extends StarlarkValue {
 

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/BUILD

@@ -24,14 +24,12 @@ java_library(
     srcs = glob(["*.java"]),
     deps = [
         "//src/main/java/com/google/devtools/build/docgen/annot",
-        "//src/main/java/com/google/devtools/build/lib/actions:artifacts",
         "//src/main/java/com/google/devtools/build/lib/cmdline",
         "//src/main/java/com/google/devtools/build/lib/collect/nestedset",
         "//src/main/java/com/google/devtools/build/lib/packages/semantics",
         "//src/main/java/com/google/devtools/build/lib/starlarkbuildapi",
         "//src/main/java/com/google/devtools/build/lib/starlarkbuildapi/apple",
         "//src/main/java/com/google/devtools/build/lib/starlarkbuildapi/core",
-        "//src/main/java/com/google/devtools/build/lib/starlarkbuildapi/go",
         "//src/main/java/com/google/devtools/build/lib/starlarkbuildapi/platform",
         "//src/main/java/net/starlark/java/annot",
         "//src/main/java/net/starlark/java/eval",

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/BazelCcModuleApi.java

@@ -14,6 +14,7 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi.cpp;
 
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.starlarkbuildapi.FileApi;
 import com.google.devtools.build.lib.starlarkbuildapi.StarlarkActionFactoryApi;
 import com.google.devtools.build.lib.starlarkbuildapi.StarlarkRuleContextApi;
@@ -23,6 +24,7 @@
 /** Utilites related to C++ support. */
 @StarlarkBuiltin(
     name = "cc_common_internal_do_not_use",
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc = "Utilities for C++ compilation, linking, and command line generation.")
 public interface BazelCcModuleApi<
         StarlarkActionFactoryT extends StarlarkActionFactoryApi,

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/BranchFdoProfileApi.java

@@ -31,7 +31,7 @@
  */
 @StarlarkBuiltin(
     name = "CcBranchFdoProfile",
-    category = DocCategory.TOP_LEVEL_TYPE,
+    category = DocCategory.TOP_LEVEL_MODULE,
     documented = false)
 public interface BranchFdoProfileApi extends StarlarkValue {
 

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CcModuleApi.java

@@ -14,6 +14,7 @@
 
 package com.google.devtools.build.lib.starlarkbuildapi.cpp;
 
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
 import com.google.devtools.build.lib.packages.semantics.BuildLanguageOptions;
@@ -39,6 +40,7 @@
 /** Utilites related to C++ support. */
 @StarlarkBuiltin(
     name = "cc_common_internal_do_not_use",
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc = "Utilities for C++ compilation, linking, and command line generation.")
 public interface CcModuleApi<
         StarlarkActionFactoryT extends StarlarkActionFactoryApi,

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/CppModuleMapApi.java

@@ -31,7 +31,7 @@
  *
  * <p>See javadoc for {@link com.google.devtools.build.lib.rules.cpp.CcModule}.
  */
-@StarlarkBuiltin(name = "CcModuleMap", category = DocCategory.TOP_LEVEL_TYPE, documented = false)
+@StarlarkBuiltin(name = "CcModuleMap", category = DocCategory.TOP_LEVEL_MODULE, documented = false)
 public interface CppModuleMapApi<FileT extends FileApi> extends StarlarkValue {
 
   @StarlarkMethod(name = "file", documented = false, useStarlarkThread = true)

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/ExtraLinkTimeLibraryApi.java

@@ -22,5 +22,5 @@
 @StarlarkBuiltin(
     name = "ExtraLinkTimeLibrary",
     documented = false,
-    category = DocCategory.TOP_LEVEL_TYPE)
+    category = DocCategory.TOP_LEVEL_MODULE)
 public interface ExtraLinkTimeLibraryApi extends StarlarkValue {}

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/FdoContextApi.java

@@ -30,7 +30,7 @@
  *
  * <p>See javadoc for {@link com.google.devtools.build.lib.rules.cpp.CcModule}.
  */
-@StarlarkBuiltin(name = "CcFdoContext", category = DocCategory.TOP_LEVEL_TYPE, documented = false)
+@StarlarkBuiltin(name = "CcFdoContext", category = DocCategory.TOP_LEVEL_MODULE, documented = false)
 public interface FdoContextApi<BranchFdoProfileT extends BranchFdoProfileApi>
     extends StarlarkValue {
 

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LinkstampApi.java

@@ -31,7 +31,7 @@
  *
  * <p>See javadoc for {@link com.google.devtools.build.lib.rules.cpp.CcModule}.
  */
-@StarlarkBuiltin(name = "CcLinkstamp", category = DocCategory.TOP_LEVEL_TYPE, documented = false)
+@StarlarkBuiltin(name = "CcLinkstamp", category = DocCategory.TOP_LEVEL_MODULE, documented = false)
 public interface LinkstampApi<FileT extends FileApi> extends StarlarkValue {
   @StarlarkMethod(name = "file", documented = false, useStarlarkThread = true)
   FileT getArtifactForStarlark(StarlarkThread thread) throws EvalException;

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/LtoBackendArtifactsApi.java

@@ -33,7 +33,7 @@
  */
 @StarlarkBuiltin(
     name = "CcLtoBackendArtifacts",
-    category = DocCategory.TOP_LEVEL_TYPE,
+    category = DocCategory.TOP_LEVEL_MODULE,
     documented = false)
 public interface LtoBackendArtifactsApi<FileT extends FileApi> extends StarlarkValue {
 

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/cpp/PyWrapCcHelperApi.java

@@ -37,7 +37,7 @@
     name = "py_wrap_cc_helper_do_not_use",
     documented = false,
     doc = "",
-    category = DocCategory.TOP_LEVEL_TYPE)
+    category = DocCategory.TOP_LEVEL_MODULE)
 public interface PyWrapCcHelperApi<
         FileT extends FileApi,
         ConstraintValueT extends ConstraintValueInfoApi,

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

@@ -15,6 +15,7 @@
 package com.google.devtools.build.lib.starlarkbuildapi.java;
 
 import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
 import com.google.devtools.build.lib.collect.nestedset.Depset.TypeException;
@@ -39,7 +40,10 @@
 import net.starlark.java.eval.StarlarkValue;
 
 /** Utilities for Java compilation support in Starlark. */
-@StarlarkBuiltin(name = "java_common", doc = "Utilities for Java compilation support in Starlark.")
+@StarlarkBuiltin(
+    name = "java_common",
+    category = DocCategory.TOP_LEVEL_MODULE,
+    doc = "Utilities for Java compilation support in Starlark.")
 public interface JavaCommonApi<
         FileT extends FileApi,
         JavaInfoT extends JavaInfoApi<FileT, ?, ?>,

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/objc/AppleCommonApi.java

@@ -15,6 +15,7 @@
 package com.google.devtools.build.lib.starlarkbuildapi.objc;
 
 import com.google.common.collect.ImmutableMap;
+import com.google.devtools.build.docgen.annot.DocCategory;
 import com.google.devtools.build.lib.analysis.TransitiveInfoCollection;
 import com.google.devtools.build.lib.analysis.config.transitions.StarlarkExposedRuleTransitionFactory;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
@@ -44,6 +45,7 @@
 /** Interface for a module with useful functions for creating apple-related rule implementations. */
 @StarlarkBuiltin(
     name = "apple_common",
+    category = DocCategory.TOP_LEVEL_MODULE,
     doc = "Functions for Starlark to access internals of the apple rule implementations.")
 public interface AppleCommonApi<
         FileApiT extends FileApi,