Skip to content

Commit

Permalink
Fix missing DocCategory values causing symbols to show up in wrong pl…
Browse files Browse the repository at this point in the history
…aces

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
  • Loading branch information
Wyverald authored and copybara-github committed Nov 9, 2022
1 parent 5318c45 commit 99a8186
Show file tree
Hide file tree
Showing 8 changed files with 21 additions and 7 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ static synchronized ImmutableMap<String, StarlarkBuiltinDoc> 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;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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 <code>module_extension</code> function.")
public static class InStarlark implements StarlarkExportable {
private final Builder builder;
@Nullable private ModuleExtension built;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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. */
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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"
Expand Down

0 comments on commit 99a8186

Please sign in to comment.