diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build/lib')
41 files changed, 377 insertions, 200 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java index fe03f57845..bbea1f5ed1 100644 --- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java +++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java @@ -28,6 +28,7 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.shell.ShellUtils; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkValue; import com.google.devtools.build.lib.syntax.EvalUtils; import com.google.devtools.build.lib.syntax.Printer; @@ -91,6 +92,7 @@ import javax.annotation.Nullable; */ @Immutable @SkylarkModule(name = "File", + category = SkylarkModuleCategory.BUILTIN, doc = "<p>This type represents a file used by the build system. It can be " + "either a source file or a derived file produced by a rule.</p>" + "<p>The File constructor is private, so you cannot call it directly to create new " diff --git a/src/main/java/com/google/devtools/build/lib/actions/Root.java b/src/main/java/com/google/devtools/build/lib/actions/Root.java index b09dfa35c8..a85e95a66a 100644 --- a/src/main/java/com/google/devtools/build/lib/actions/Root.java +++ b/src/main/java/com/google/devtools/build/lib/actions/Root.java @@ -17,6 +17,7 @@ package com.google.devtools.build.lib.actions; import com.google.common.annotations.VisibleForTesting; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.build.lib.vfs.PathFragment; @@ -43,6 +44,7 @@ import javax.annotation.Nullable; * that is the root of the merged directory tree. */ @SkylarkModule(name = "root", + category = SkylarkModuleCategory.BUILTIN, doc = "A root for files. The roots are the directories containing files, and they are mapped " + "together into a single directory tree to form the execution environment.") public final class Root implements Comparable<Root>, Serializable { diff --git a/src/main/java/com/google/devtools/build/lib/analysis/FileProvider.java b/src/main/java/com/google/devtools/build/lib/analysis/FileProvider.java index 0b4dd3b712..9d6e4e173c 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/FileProvider.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/FileProvider.java @@ -21,6 +21,7 @@ import com.google.devtools.build.lib.collect.nestedset.Order; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; /** * A representation of the concept "this transitive info provider builds these files". @@ -28,7 +29,11 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; * <p>Every transitive info collection contains at least this provider. */ @Immutable -@SkylarkModule(name = "file_provider", doc = "An interface for rules that provide files.") +@SkylarkModule( + name = "file_provider", + doc = "An interface for rules that provide files.", + category = SkylarkModuleCategory.PROVIDER +) public final class FileProvider implements TransitiveInfoProvider { public static final FileProvider EMPTY = new FileProvider(NestedSetBuilder.<Artifact>emptySet(Order.STABLE_ORDER)); diff --git a/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java b/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java index 35c0b9aa8f..8077a59d35 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java @@ -21,14 +21,13 @@ import com.google.devtools.build.lib.actions.RunfilesSupplier; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import javax.annotation.Nullable; -/** - * Returns information about executables produced by a target and the files needed to run it. - */ +/** Returns information about executables produced by a target and the files needed to run it. */ @Immutable -@SkylarkModule(name = "FilesToRunProvider", doc = "") +@SkylarkModule(name = "FilesToRunProvider", doc = "", category = SkylarkModuleCategory.PROVIDER) public final class FilesToRunProvider implements TransitiveInfoProvider { /** The name of the field in Skylark used to access this class. */ public static final String SKYLARK_NAME = "files_to_run"; diff --git a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java index d1f1434a39..0de1b2d513 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java @@ -32,6 +32,7 @@ import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.packages.BuildType; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.build.lib.vfs.PathFragment; @@ -61,7 +62,11 @@ import javax.annotation.Nullable; * manifests" (see {@link PruningManifest}). */ @Immutable -@SkylarkModule(name = "runfiles", doc = "An interface for a set of runfiles.") +@SkylarkModule( + name = "runfiles", + category = SkylarkModuleCategory.NONE, + doc = "An interface for a set of runfiles." +) public final class Runfiles { private static final Function<SymlinkEntry, Artifact> TO_ARTIFACT = new Function<SymlinkEntry, Artifact>() { diff --git a/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java b/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java index ab53315111..6dd8dd7f13 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java @@ -17,26 +17,29 @@ package com.google.devtools.build.lib.analysis; import com.google.devtools.build.lib.analysis.config.BuildConfiguration; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import javax.annotation.Nullable; /** * Multiple {@link TransitiveInfoProvider}s bundled together. * - * Represents the information made available by a {@link ConfiguredTarget} to other ones that - * depend on it. For more information about the analysis phase, see - * {@link com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory}. + * <p>Represents the information made available by a {@link ConfiguredTarget} to other ones that + * depend on it. For more information about the analysis phase, see {@link + * com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory}. * - * <p>Implementations of build rules should <b>not</b> hold on to references to the - * {@link TransitiveInfoCollection}s representing their direct prerequisites in order to reduce - * their memory footprint (otherwise, the referenced object could refer one of its direct - * dependencies in turn, thereby making the size of the objects reachable from a single instance - * unbounded). + * <p>Implementations of build rules should <b>not</b> hold on to references to the {@link + * TransitiveInfoCollection}s representing their direct prerequisites in order to reduce their + * memory footprint (otherwise, the referenced object could refer one of its direct dependencies in + * turn, thereby making the size of the objects reachable from a single instance unbounded). * * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory * @see TransitiveInfoProvider */ -@SkylarkModule(name = "Target", doc = +@SkylarkModule( + name = "Target", + category = SkylarkModuleCategory.BUILTIN, + doc = "A BUILD target. It is essentially a <code>struct</code> with the following fields:" + "<ul>" + "<li><h3 id=\"modules.Target.label\">label</h3><code><a class=\"anchor\" " diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java index 0499743422..012e72062c 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java @@ -53,6 +53,7 @@ import com.google.devtools.build.lib.packages.Target; import com.google.devtools.build.lib.rules.test.TestActionBuilder; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.CPU; import com.google.devtools.build.lib.util.Fingerprint; import com.google.devtools.build.lib.util.OS; @@ -108,6 +109,7 @@ import javax.annotation.Nullable; * <pre>c1.equals(c2) <=> c1==c2.</pre> */ @SkylarkModule(name = "configuration", + category = SkylarkModuleCategory.BUILTIN, doc = "Data required for the analysis of a target that comes from targets that " + "depend on it and not targets that it depends on.") public final class BuildConfiguration { diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java b/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java index 3fdd4c8e0a..fb1f4adcf7 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/config/FragmentCollection.java @@ -19,6 +19,7 @@ import com.google.devtools.build.lib.analysis.RuleContext; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.packages.Attribute.ConfigurationTransition; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.ClassObject; import javax.annotation.Nullable; @@ -28,7 +29,9 @@ import javax.annotation.Nullable; */ // Documentation can be found at ctx.fragments @Immutable -@SkylarkModule(name = "fragments", doc = "Possible fields are " +@SkylarkModule(name = "fragments", + category = SkylarkModuleCategory.NONE, + doc = "Possible fields are " + "<a href=\"apple.html\">apple</a>, <a href=\"cpp.html\">cpp</a>, " + "<a href=\"java.html\">java</a>, <a href=\"jvm.html\">jvm</a> and " + "<a href=\"objc.html\">objc</a>. " diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkExecutionResult.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkExecutionResult.java index ad2e7b60a8..d306a52d4a 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkExecutionResult.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkExecutionResult.java @@ -21,6 +21,7 @@ import com.google.devtools.build.lib.shell.CommandException; import com.google.devtools.build.lib.shell.CommandResult; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.EvalException; import com.google.devtools.build.lib.util.Preconditions; @@ -37,6 +38,7 @@ import java.util.Map; */ @SkylarkModule( name = "exec_result", + category = SkylarkModuleCategory.NONE, doc = "A structure storing result of repository_ctx.execute() method. It contains the standard" + " output stream content, the standard error stream content and the execution return" diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkOS.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkOS.java index 05ba5cdc44..2c45c8e697 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkOS.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkOS.java @@ -18,15 +18,15 @@ import com.google.common.collect.ImmutableMap; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import java.util.Map; -/** - * A Skylark structure to deliver information about the system we are running on. - */ +/** A Skylark structure to deliver information about the system we are running on. */ @Immutable @SkylarkModule( name = "repository_os", + category = SkylarkModuleCategory.NONE, doc = "Various data about the current platform Bazel is running on." ) final class SkylarkOS { diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java index 3e29c7048e..cadadec95d 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java @@ -18,6 +18,7 @@ import com.google.common.collect.ImmutableList; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.vfs.Path; import java.io.IOException; @@ -30,7 +31,10 @@ import java.util.List; * something other than a SkylarkRepositoryContext. */ @Immutable -@SkylarkModule(name = "path", doc = "A structure representing a file to be used inside a repository" +@SkylarkModule( + name = "path", + category = SkylarkModuleCategory.NONE, + doc = "A structure representing a file to be used inside a repository" ) final class SkylarkPath { private final Path path; diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java index ec6a353c9a..ad2290adb6 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java @@ -32,6 +32,7 @@ import com.google.devtools.build.lib.skyframe.InconsistentFilesystemException; import com.google.devtools.build.lib.skyframe.PackageLookupValue; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.ClassObject.SkylarkClassObject; import com.google.devtools.build.lib.syntax.EvalException; import com.google.devtools.build.lib.syntax.Runtime; @@ -53,11 +54,10 @@ import java.nio.charset.StandardCharsets; import java.util.List; import java.util.Map; -/** - * Skylark API for the repository_rule's context. - */ +/** Skylark API for the repository_rule's context. */ @SkylarkModule( name = "repository_ctx", + category = SkylarkModuleCategory.BUILTIN, doc = "The context of the repository rule containing" + " helper functions and information about attributes. You get a repository_ctx object" diff --git a/src/main/java/com/google/devtools/build/lib/cmdline/Label.java b/src/main/java/com/google/devtools/build/lib/cmdline/Label.java index 75d4677365..19f346f48b 100644 --- a/src/main/java/com/google/devtools/build/lib/cmdline/Label.java +++ b/src/main/java/com/google/devtools/build/lib/cmdline/Label.java @@ -22,6 +22,7 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.concurrent.ThreadSafety.ThreadSafe; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkPrintableValue; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.util.StringCanonicalizer; @@ -34,15 +35,20 @@ import java.io.ObjectInputStream; import java.io.Serializable; /** - * A class to identify a BUILD target. All targets belong to exactly one package. - * The name of a target is called its label. A typical label looks like this: - * //dir1/dir2:target_name where 'dir1/dir2' identifies the package containing a BUILD file, - * and 'target_name' identifies the target within the package. + * A class to identify a BUILD target. All targets belong to exactly one package. The name of a + * target is called its label. A typical label looks like this: //dir1/dir2:target_name where + * 'dir1/dir2' identifies the package containing a BUILD file, and 'target_name' identifies the + * target within the package. * * <p>Parsing is robust against bad input, for example, from the command line. */ -@SkylarkModule(name = "Label", doc = "A BUILD target identifier.") -@Immutable @ThreadSafe +@SkylarkModule( + name = "Label", + category = SkylarkModuleCategory.BUILTIN, + doc = "A BUILD target identifier." +) +@Immutable +@ThreadSafe public final class Label implements Comparable<Label>, Serializable, SkylarkPrintableValue { public static final PathFragment EXTERNAL_PACKAGE_NAME = new PathFragment("external"); public static final PathFragment EXTERNAL_PACKAGE_FILE_NAME = new PathFragment("WORKSPACE"); diff --git a/src/main/java/com/google/devtools/build/lib/packages/Attribute.java b/src/main/java/com/google/devtools/build/lib/packages/Attribute.java index 7e8cfffec5..5d4fe22386 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/Attribute.java +++ b/src/main/java/com/google/devtools/build/lib/packages/Attribute.java @@ -26,6 +26,7 @@ import com.google.common.collect.Sets; import com.google.devtools.build.lib.analysis.TransitiveInfoProvider; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.ClassObject; import com.google.devtools.build.lib.syntax.ClassObject.SkylarkClassObject; import com.google.devtools.build.lib.syntax.EvalException; @@ -163,10 +164,11 @@ public final class Attribute implements Comparable<Attribute> { } /** - * Declaration how the configuration should change when following a label or - * label list attribute. + * Declaration how the configuration should change when following a label or label list attribute. */ - @SkylarkModule(name = "ConfigurationTransition", doc = + @SkylarkModule(name = "ConfigurationTransition", + category = SkylarkModuleCategory.NONE, + doc = "Declares how the configuration should change when following a dependency. " + "It can be either <a href=\"globals.html#DATA_CFG\">DATA_CFG</a> or " + "<a href=\"globals.html#HOST_CFG\">HOST_CFG</a>.") diff --git a/src/main/java/com/google/devtools/build/lib/packages/SkylarkAspect.java b/src/main/java/com/google/devtools/build/lib/packages/SkylarkAspect.java index 625785de59..1a785092b4 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/SkylarkAspect.java +++ b/src/main/java/com/google/devtools/build/lib/packages/SkylarkAspect.java @@ -19,6 +19,7 @@ import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableSet; import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkValue; import com.google.devtools.build.lib.syntax.BaseFunction; import com.google.devtools.build.lib.syntax.Environment; @@ -29,15 +30,15 @@ import com.google.devtools.build.lib.util.Preconditions; import javax.annotation.Nullable; -/** - * A Skylark value that is a result of an 'aspect(..)' function call. - */ +/** A Skylark value that is a result of an 'aspect(..)' function call. */ @SkylarkModule( name = "Aspect", + category = SkylarkModuleCategory.NONE, doc = "For more information about Aspects, please consult the <a href=\"globals.html#aspect\">" + "documentation of the aspect function</a> or the " - + "<a href=\"../aspects.md\">introduction to Aspects</a>.") + + "<a href=\"../aspects.md\">introduction to Aspects</a>." +) public class SkylarkAspect implements SkylarkValue { private final BaseFunction implementation; private final ImmutableList<String> attributeAspects; diff --git a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java index 31208ba212..190a46b327 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java +++ b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java @@ -16,6 +16,7 @@ package com.google.devtools.build.lib.packages; import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature; import com.google.devtools.build.lib.syntax.BuiltinFunction; import com.google.devtools.build.lib.syntax.Environment; @@ -30,7 +31,10 @@ import com.google.devtools.build.lib.syntax.Type.ConversionException; /** * A class for the Skylark native module. */ -@SkylarkModule(name = "native", namespace = true, doc = +@SkylarkModule(name = "native", namespace = true, + title = "Native Module", + category = SkylarkModuleCategory.TOP_LEVEL_TYPE, + 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. <code>native.cc_library</code>. " + "Note that the native module is only available in the loading phase " @@ -46,11 +50,11 @@ public class SkylarkNativeModule { returnType = SkylarkList.class, doc = "Glob returns a list of every file in the current package that:<ul>\n" - + "<li>Matches at least one pattern in <code>include</code>.</li>\n" - + "<li>Does not match any of the patterns in <code>exclude</code> " - + "(default <code>[]</code>).</li></ul>\n" - + "If the <code>exclude_directories</code> argument is enabled (set to <code>1</code>)," - + " files of type directory will be omitted from the results (default <code>1</code>).", + + "<li>Matches at least one pattern in <code>include</code>.</li>\n" + + "<li>Does not match any of the patterns in <code>exclude</code> " + + "(default <code>[]</code>).</li></ul>\n" + + "If the <code>exclude_directories</code> argument is enabled (set to <code>1</code>)," + + " files of type directory will be omitted from the results (default <code>1</code>).", parameters = { @Param( name = "include", diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java index 7038b43424..5b0fd57988 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java @@ -26,6 +26,7 @@ import com.google.devtools.build.lib.packages.BuildType; import com.google.devtools.build.lib.packages.SkylarkAspect; import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature; import com.google.devtools.build.lib.syntax.BuiltinFunction; import com.google.devtools.build.lib.syntax.Environment; @@ -54,13 +55,14 @@ import javax.annotation.Nullable; /** * A helper class to provide Attr module in Skylark. * - * <p>It exposes functions (e.g. 'attr.string', 'attr.label_list', etc.) to Skylark - * users. The functions are executed through reflection. As everywhere in Skylark, - * arguments are type-checked with the signature and cannot be null. + * <p>It exposes functions (e.g. 'attr.string', 'attr.label_list', etc.) to Skylark users. The + * functions are executed through reflection. As everywhere in Skylark, arguments are type-checked + * with the signature and cannot be null. */ @SkylarkModule( name = "attr", namespace = true, + category = SkylarkModuleCategory.BUILTIN, doc = "Module for creating new attributes. " + "They are only for use with the <a href=\"globals.html#rule\">rule</a> function." @@ -1054,9 +1056,14 @@ public final class SkylarkAttr { } }; - /** - * A descriptor of an attribute defined in Skylark. - */ + /** A descriptor of an attribute defined in Skylark. */ + @SkylarkModule( + name = "attr_defintion", + category = SkylarkModuleCategory.NONE, + doc = + "Representation of a definition of an attribute; cobnstructed by <code>attr.*</code>" + + " functions." + ) public static final class Descriptor { private final Attribute.Builder<?> attributeBuilder; private final ImmutableList<SkylarkAspect> aspects; diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java index 8e107b93a3..7fd5fe4dc4 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java @@ -20,6 +20,7 @@ import com.google.devtools.build.lib.actions.Artifact; import com.google.devtools.build.lib.collect.nestedset.NestedSet; import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature; import com.google.devtools.build.lib.syntax.BuiltinFunction; import com.google.devtools.build.lib.syntax.Environment; @@ -27,11 +28,13 @@ import com.google.devtools.build.lib.syntax.SkylarkList.MutableList; import com.google.devtools.build.lib.syntax.SkylarkNestedSet; import com.google.devtools.build.lib.syntax.SkylarkSignatureProcessor; -/** - * A Skylark module class to create memory efficient command lines. - */ -@SkylarkModule(name = "cmd_helper", namespace = true, - doc = "Module for creating memory efficient command lines.") +/** A Skylark module class to create memory efficient command lines. */ +@SkylarkModule( + name = "cmd_helper", + namespace = true, + category = SkylarkModuleCategory.BUILTIN, + doc = "Module for creating memory efficient command lines." +) public class SkylarkCommandLine { @SkylarkSignature(name = "join_paths", objectType = SkylarkCommandLine.class, diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkFileType.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkFileType.java index 94ca4c8b5a..6b31fd8761 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkFileType.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkFileType.java @@ -18,17 +18,20 @@ import com.google.common.collect.ImmutableList; import com.google.devtools.build.lib.actions.Artifact; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.FileType; import com.google.devtools.build.lib.util.FileTypeSet; import java.util.List; -/** - * A wrapper class for FileType and FileTypeSet functionality in Skylark. - */ -@SkylarkModule(name = "FileType", - doc = "Deprecated. File type for file filtering. Can be used to filter collections of labels " - + "for certain file types.") +/** A wrapper class for FileType and FileTypeSet functionality in Skylark. */ +@SkylarkModule( + name = "FileType", + category = SkylarkModuleCategory.NONE, + doc = + "Deprecated. File type for file filtering. Can be used to filter collections of labels " + + "for certain file types." +) public class SkylarkFileType { private final FileType fileType; diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java index 5c5baba790..a956e4d467 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java @@ -46,6 +46,7 @@ import com.google.devtools.build.lib.shell.ShellUtils; import com.google.devtools.build.lib.shell.ShellUtils.TokenizationException; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.ClassObject.SkylarkClassObject; import com.google.devtools.build.lib.syntax.EvalException; import com.google.devtools.build.lib.syntax.FuncallExpression.FuncallException; @@ -69,13 +70,16 @@ import java.util.Set; import javax.annotation.Nullable; -/** - * A Skylark API for the ruleContext. - */ -@SkylarkModule(name = "ctx", doc = "The context of the rule containing helper functions and " - + "information about attributes, depending targets and outputs. " - + "You get a ctx object as an argument to the <code>implementation</code> function when " - + "you create a rule.") +/** A Skylark API for the ruleContext. */ +@SkylarkModule( + name = "ctx", + category = SkylarkModuleCategory.BUILTIN, + doc = + "The context of the rule containing helper functions and " + + "information about attributes, depending targets and outputs. " + + "You get a ctx object as an argument to the <code>implementation</code> function when " + + "you create a rule." +) public final class SkylarkRuleContext { private static final String DOC_NEW_FILE_TAIL = "Does not actually create a file on the file " @@ -330,6 +334,7 @@ public final class SkylarkRuleContext { @SkylarkModule( name = "rule_attributes", + category = SkylarkModuleCategory.NONE, doc = "Information about attributes of a rule an aspect is applied to." ) private static class SkylarkRuleAttributesCollection { diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java index e64bc92f61..ed8434de93 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java @@ -27,17 +27,21 @@ import com.google.devtools.build.lib.rules.java.JavaRuleOutputJarsProvider; import com.google.devtools.build.lib.rules.java.JavaRuleOutputJarsProvider.OutputJar; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import javax.annotation.Nullable; /** - * A class that exposes the Android providers to Skylark. It is intended to provide a - * simple and stable interface for Skylark users. + * A class that exposes the Android providers to Skylark. It is intended to provide a simple and + * stable interface for Skylark users. */ @SkylarkModule( name = "AndroidSkylarkApiProvider", - doc = "Provides access to information about Android rules. Every Android-related target provides " - + "this struct, accessible as a 'java' field on a Target struct." + title = "android", + category = SkylarkModuleCategory.PROVIDER, + doc = + "Provides access to information about Android rules. Every Android-related target provides " + + "this struct, accessible as a 'android' field on a Target struct." ) public class AndroidSkylarkApiProvider extends SkylarkApiProvider { /** The name of the field in Skylark used to access this class. */ @@ -148,12 +152,11 @@ public class AndroidSkylarkApiProvider extends SkylarkApiProvider { }))); } - /** - * Helper class to provide information about IDLs related to this rule. - */ + /** Helper class to provide information about IDLs related to this rule. */ @SkylarkModule( - name = "AndroidSkylarkIdlInfo", - doc = "Provides access to information about Android rules" + name = "AndroidSkylarkIdlInfo", + category = SkylarkModuleCategory.NONE, + doc = "Provides access to information about Android rules" ) public class IdlInfo { @SkylarkCallable( diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java index ebc8c9831f..c8fe054b50 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java @@ -32,6 +32,7 @@ import com.google.devtools.build.lib.rules.apple.AppleCommandLineOptions.AppleBi import com.google.devtools.build.lib.rules.apple.Platform.PlatformType; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import java.util.ArrayList; @@ -41,10 +42,12 @@ import java.util.Map; import javax.annotation.Nullable; -/** - * A configuration containing flags required for Apple platforms and tools. - */ -@SkylarkModule(name = "apple", doc = "A configuration fragment for Apple platforms") +/** A configuration containing flags required for Apple platforms and tools. */ +@SkylarkModule( + name = "apple", + doc = "A configuration fragment for Apple platforms", + category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT +) @Immutable public class AppleConfiguration extends BuildConfiguration.Fragment { /** diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/DottedVersion.java b/src/main/java/com/google/devtools/build/lib/rules/apple/DottedVersion.java index ebd22f4146..7d97b502d3 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/DottedVersion.java +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/DottedVersion.java @@ -21,6 +21,7 @@ import com.google.common.collect.ImmutableList; import com.google.common.collect.Ordering; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import java.util.ArrayList; import java.util.Objects; @@ -36,8 +37,7 @@ import java.util.regex.Pattern; * * <p>Dotted versions are ordered using natural integer sorting on components in order from first to * last where any missing element is considered to have the value 0 if they don't contain any - * non-numeric characters. For example: - * <pre> + * non-numeric characters. For example: <pre> * 3.1.25 > 3.1.1 * 3.1.20 > 3.1.2 * 3.1.1 > 3.1 @@ -50,8 +50,7 @@ import java.util.regex.Pattern; * component with a smaller integer. If the integers are the same, the alphabetic sequences are * compared lexicographically, and if <i>they</i> turn out to be the same, the final (optional) * integer is compared. As with the leading integer, this final integer is considered to be 0 if not - * present. For example: - * <pre> + * present. For example: <pre> * 3.1.1 > 3.1.1beta3 * 3.1.1beta1 > 3.1.0 * 3.1 > 3.1.0alpha1 @@ -66,8 +65,10 @@ import java.util.regex.Pattern; */ @SkylarkModule( name = "DottedVersion", - doc = "A value representing a version with multiple components, seperated by periods, such as " - + "1.2.3.4." + category = SkylarkModuleCategory.NONE, + doc = + "A value representing a version with multiple components, seperated by periods, such as " + + "1.2.3.4." ) public final class DottedVersion implements Comparable<DottedVersion> { private static final Splitter DOT_SPLITTER = Splitter.on('.'); diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/Platform.java b/src/main/java/com/google/devtools/build/lib/rules/apple/Platform.java index 7a8b1d1990..987c4fd0ef 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/Platform.java +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/Platform.java @@ -17,6 +17,7 @@ package com.google.devtools.build.lib.rules.apple; import com.google.common.collect.ImmutableSet; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import java.util.Locale; @@ -24,10 +25,12 @@ import java.util.Set; import javax.annotation.Nullable; -/** - * An enum that can be used to distinguish between various apple platforms. - */ -@SkylarkModule(name = "platform", doc = "Distinguishes between various apple platforms.") +/** An enum that can be used to distinguish between various apple platforms. */ +@SkylarkModule( + name = "platform", + category = SkylarkModuleCategory.NONE, + doc = "Distinguishes between various apple platforms." +) public enum Platform { IOS_DEVICE("iPhoneOS", PlatformType.IOS), diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java index 4f250b7b18..cd5f64282b 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java @@ -21,16 +21,21 @@ import com.google.devtools.build.lib.collect.nestedset.NestedSetBuilder; import com.google.devtools.build.lib.rules.SkylarkApiProvider; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.vfs.PathFragment; /** - * A class that exposes the C++ providers to Skylark. It is intended to provide a - * simple and stable interface for Skylark users. + * A class that exposes the C++ providers to Skylark. It is intended to provide a simple and stable + * interface for Skylark users. */ @SkylarkModule( - name = "CcSkylarkApiProvider", doc = "Provides access to information about C++ rules. " - + "Every C++-related target provides this struct, accessible as a 'cc' field on " - + "a Target struct.") + name = "CcSkylarkApiProvider", + category = SkylarkModuleCategory.PROVIDER, + doc = + "Provides access to information about C++ rules. " + + "Every C++-related target provides this struct, accessible as a 'cc' field on " + + "a Target struct." +) public final class CcSkylarkApiProvider extends SkylarkApiProvider { /** The name of the field in Skylark used to access this class. */ public static final String NAME = "cc"; diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java index 9889401014..0d5d16430a 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java @@ -40,6 +40,7 @@ import com.google.devtools.build.lib.events.EventHandler; import com.google.devtools.build.lib.rules.cpp.CppConfigurationLoader.CppConfigurationParameters; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.vfs.Path; import com.google.devtools.build.lib.vfs.PathFragment; @@ -60,12 +61,15 @@ import java.util.Map; import java.util.Set; /** - * This class represents the C/C++ parts of the {@link BuildConfiguration}, - * including the host architecture, target architecture, compiler version, and - * a standard library version. It has information about the tools locations and - * the flags required for compiling. + * This class represents the C/C++ parts of the {@link BuildConfiguration}, including the host + * architecture, target architecture, compiler version, and a standard library version. It has + * information about the tools locations and the flags required for compiling. */ -@SkylarkModule(name = "cpp", doc = "A configuration fragment for C++") +@SkylarkModule( + name = "cpp", + doc = "A configuration fragment for C++", + category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT +) @Immutable public class CppConfiguration extends BuildConfiguration.Fragment { diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java index 76750e72ea..7a577eca27 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java @@ -21,12 +21,14 @@ import com.google.devtools.build.lib.collect.nestedset.NestedSet; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; /** * A class that provides compilation information in Java rules, for perusal of aspects and tools. */ @SkylarkModule( - name = "JavaCompilationInfo", + name = "java_compilation_info", + category = SkylarkModuleCategory.NONE, doc = "Provides access to compilation information for Java rules" ) @Immutable diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java index 8036b9cd2b..27f7d52443 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java @@ -28,17 +28,20 @@ import com.google.devtools.build.lib.events.Event; import com.google.devtools.build.lib.events.EventHandler; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.common.options.TriState; import java.util.List; import javax.annotation.Nullable; -/** - * A java compiler configuration containing the flags required for compilation. - */ +/** A java compiler configuration containing the flags required for compilation. */ @Immutable -@SkylarkModule(name = "java", doc = "A java compiler configuration") +@SkylarkModule( + name = "java", + doc = "A java compiler configuration", + category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT +) public final class JavaConfiguration extends Fragment { /** * Values for the --experimental_java_classpath option diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java index c676b2243f..12cd42f15f 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java @@ -20,15 +20,15 @@ import com.google.devtools.build.lib.collect.nestedset.NestedSet; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import javax.annotation.Nullable; -/** - * The collection of gen jars from the transitive closure. - */ +/** The collection of gen jars from the transitive closure. */ @Immutable @SkylarkModule( - name = "JavaAnnotationProcessing", + name = "java_annotation-processing", + category = SkylarkModuleCategory.NONE, doc = "Information about jars that are a result of annotation processing for a Java rule." ) public final class JavaGenJarsProvider implements TransitiveInfoProvider { diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java index 11d16fd2e8..3cbcf252fc 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java @@ -20,25 +20,27 @@ import com.google.devtools.build.lib.analysis.TransitiveInfoProvider; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import javax.annotation.Nullable; -/** - * Provides information about jar files produced by a Java rule. - */ +/** Provides information about jar files produced by a Java rule. */ @Immutable -@SkylarkModule(name = "JavaOutputJars", doc = "Information about outputs of a Java rule") +@SkylarkModule( + name = "java_output_jars", + category = SkylarkModuleCategory.NONE, + doc = "Information about outputs of a Java rule" +) public final class JavaRuleOutputJarsProvider implements TransitiveInfoProvider { public static final JavaRuleOutputJarsProvider EMPTY = new JavaRuleOutputJarsProvider(ImmutableList.<OutputJar>of(), null); - /** - * A collection of artifacts associated with a jar output. - */ + /** A collection of artifacts associated with a jar output. */ @SkylarkModule( - name = "JavaOutput", + name = "java_output", + category = SkylarkModuleCategory.NONE, doc = "Java classes jar, together with their associated source and interface archives" ) @Immutable diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java index eb6e7fa89e..6d5f353646 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java @@ -22,15 +22,20 @@ import com.google.devtools.build.lib.collect.nestedset.Order; import com.google.devtools.build.lib.rules.SkylarkApiProvider; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; /** - * A class that exposes the Java providers to Skylark. It is intended to provide a - * simple and stable interface for Skylark users. + * A class that exposes the Java providers to Skylark. It is intended to provide a simple and stable + * interface for Skylark users. */ @SkylarkModule( - name = "JavaSkylarkApiProvider", - doc = "Provides access to information about Java rules. Every Java-related target provides " - + "this struct, accessible as a 'java' field on a Target struct.") + name = "JavaSkylarkApiProvider", + title = "java", + category = SkylarkModuleCategory.PROVIDER, + doc = + "Provides access to information about Java rules. Every Java-related target provides " + + "this struct, accessible as a 'java' field on a Target struct." +) public final class JavaSkylarkApiProvider extends SkylarkApiProvider { /** The name of the field in Skylark used to access this class. */ public static final String NAME = "java"; diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/Jvm.java b/src/main/java/com/google/devtools/build/lib/rules/java/Jvm.java index edecece6aa..37271b8b48 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/Jvm.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/Jvm.java @@ -20,17 +20,21 @@ import com.google.devtools.build.lib.cmdline.Label; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.OsUtils; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.vfs.PathFragment; /** - * This class represents a Java virtual machine with a host system and a path. - * If the JVM comes from the client, it can optionally also contain a label - * pointing to a target that contains all the necessary files. + * This class represents a Java virtual machine with a host system and a path. If the JVM comes from + * the client, it can optionally also contain a label pointing to a target that contains all the + * necessary files. */ -@SkylarkModule(name = "jvm", - doc = "A configuration fragment representing the Java virtual machine.") +@SkylarkModule( + name = "jvm", + category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT, + doc = "A configuration fragment representing the Java virtual machine." +) @Immutable public final class Jvm extends BuildConfiguration.Fragment { private final PathFragment javaHome; diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java index 69596dd723..8da579bde8 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java @@ -24,15 +24,18 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.rules.apple.DottedVersion; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.vfs.Path; import javax.annotation.Nullable; -/** - * A compiler configuration containing flags required for Objective-C compilation. - */ -@SkylarkModule(name = "objc", doc = "A configuration fragment for Objective-C") +/** A compiler configuration containing flags required for Objective-C compilation. */ +@SkylarkModule( + name = "objc", + category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT, + doc = "A configuration fragment for Objective-C" +) @Immutable public class ObjcConfiguration extends BuildConfiguration.Fragment { @VisibleForTesting diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcProvider.java b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcProvider.java index d16f80bf64..7bf91b8353 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcProvider.java @@ -29,6 +29,7 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.rules.cpp.CppModuleMap; import com.google.devtools.build.lib.rules.cpp.LinkerInputs; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.ClassObject.SkylarkClassObject; import com.google.devtools.build.lib.syntax.EvalUtils; import com.google.devtools.build.lib.util.Preconditions; @@ -43,7 +44,11 @@ import java.util.Map; * deps that are needed for building Objective-C rules. */ @Immutable -@SkylarkModule(name = "ObjcProvider", doc = "A provider for compilation and linking of objc.") +@SkylarkModule( + name = "ObjcProvider", + category = SkylarkModuleCategory.PROVIDER, + doc = "A provider for compilation and linking of objc." +) public final class ObjcProvider extends SkylarkClassObject implements TransitiveInfoProvider { /** diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModule.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModule.java index 0d9d63d1ac..d6ff2351f6 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModule.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModule.java @@ -30,12 +30,16 @@ public @interface SkylarkModule { String name(); + String title() default ""; + String doc(); boolean documented() default true; boolean namespace() default false; + SkylarkModuleCategory category() default SkylarkModuleCategory.TOP_LEVEL_TYPE; + /** Helper method to quickly get the SkylarkModule name of a class (if present). */ public static final class Resolver { /** diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModuleCategory.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModuleCategory.java new file mode 100644 index 0000000000..9602556ad7 --- /dev/null +++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModuleCategory.java @@ -0,0 +1,64 @@ +// Copyright 2016 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +package com.google.devtools.build.lib.skylarkinterface; + +/** A category of a Java type exposed to Skylark */ +public enum SkylarkModuleCategory { + CONFIGURATION_FRAGMENT("Configuration Fragments", + "Configuration fragments give rules access to " + + "language-specific parts of <a href=\"/docs/skylark/lib/configuration.html\">" + + "configuration</a>. " + + "<p>Rule implementations can get them using " + + "<code><a href=\"/docs/skylark/lib/ctx.html\">ctx</a>." + + "fragments.<i>[fragment name]</i></code>"), + + PROVIDER("Providers", + "<a href=\"/docs/skylark/rules.html#providers\">Providers</a> give rules access " + + " to information from their dependencies. " + + " <p>This section lists providers available on built-in rules. Rule implementation " + + " functions can access them via " + + "<code><a href=\"/docs/skylark/lib/ctx.html\">target</a>.<i>[provider name]</i></code>." + ), + + BUILTIN("Built-in Types and Modules", ""), + + TOP_LEVEL_TYPE, + NONE; + + private final String title; + private final String description; + + + SkylarkModuleCategory(String title, String description) { + this.title = title; + this.description = description; + } + + SkylarkModuleCategory() { + this.title = null; + this.description = null; + } + + public String getTemplateIdentifier() { + return name().toLowerCase().replace("_", "-"); + } + + public String getTitle() { + return title; + } + + public String getDescription() { + return description; + } +} diff --git a/src/main/java/com/google/devtools/build/lib/syntax/ClassObject.java b/src/main/java/com/google/devtools/build/lib/syntax/ClassObject.java index cb13c65a30..638936d9c3 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/ClassObject.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/ClassObject.java @@ -22,6 +22,7 @@ import com.google.common.collect.Sets.SetView; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.util.Preconditions; import java.io.Serializable; @@ -53,15 +54,17 @@ public interface ClassObject { */ @Nullable String errorMessage(String name); - /** - * An implementation class of ClassObject for structs created in Skylark code. - */ + /** An implementation class of ClassObject for structs created in Skylark code. */ // TODO(bazel-team): maybe move the SkylarkModule annotation to the ClassObject interface? @Immutable - @SkylarkModule(name = "struct", - doc = "A special language element to support structs (i.e. simple value objects). " - + "See the global <a href=\"globals.html#struct\">struct</a> function " - + "for more details.") + @SkylarkModule( + name = "struct", + category = SkylarkModuleCategory.BUILTIN, + doc = + "A special language element to support structs (i.e. simple value objects). " + + "See the global <a href=\"globals.html#struct\">struct</a> function " + + "for more details." + ) public class SkylarkClassObject implements ClassObject, Serializable { /** Error message to use when errorMessage argument is null. */ private static final String DEFAULT_ERROR_MESSAGE = "'struct' object has no attribute '%s'"; diff --git a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java index 37d489f892..ad525347ca 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java @@ -26,6 +26,7 @@ import com.google.devtools.build.lib.events.Event; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature; import com.google.devtools.build.lib.syntax.ClassObject.SkylarkClassObject; import com.google.devtools.build.lib.syntax.SkylarkList.MutableList; @@ -2227,11 +2228,10 @@ public class MethodLibrary { } }; - /** - * Skylark String module. - */ + /** Skylark String module. */ @SkylarkModule( name = "string", + category = SkylarkModuleCategory.BUILTIN, doc = "A language built-in type to support strings. " + "Examples of string literals:<br>" diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java index 8cb1926bb5..254264ea49 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java @@ -16,6 +16,7 @@ package com.google.devtools.build.lib.syntax; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.SkylarkMutable.MutableMap; import java.util.Map; @@ -26,8 +27,9 @@ import javax.annotation.Nullable; /** * Skylark Dict module. */ -@SkylarkModule(name = "dict", doc = - "A language built-in type to support dicts. " +@SkylarkModule(name = "dict", + category = SkylarkModuleCategory.BUILTIN, + doc = "A language built-in type to support dicts. " + "Example of dict literal:<br>" + "<pre class=\"language-python\">d = {\"a\": 2, \"b\": 5}</pre>" + "Use brackets to access elements:<br>" diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java index 5855824bb1..890d16c46e 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java @@ -19,6 +19,7 @@ import com.google.common.collect.Iterables; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.SkylarkMutable.MutableCollection; import java.util.ArrayList; @@ -30,13 +31,14 @@ import java.util.RandomAccess; import javax.annotation.Nullable; -/** - * A class to handle lists and tuples in Skylark. - */ -@SkylarkModule(name = "sequence", documented = false, - doc = "common type of lists and tuples") - public abstract class SkylarkList<E> - extends MutableCollection<E> implements List<E>, RandomAccess { +/** A class to handle lists and tuples in Skylark. */ +@SkylarkModule( + name = "sequence", + documented = false, + category = SkylarkModuleCategory.BUILTIN, + doc = "common type of lists and tuples" +) +public abstract class SkylarkList<E> extends MutableCollection<E> implements List<E>, RandomAccess { /** * Returns an ImmutableList object with the current underlying contents of this SkylarkList. @@ -192,11 +194,10 @@ import javax.annotation.Nullable; return castList(getContentsUnsafe(), type, description); } - /** - * A class for mutable lists. - */ + /** A class for mutable lists. */ @SkylarkModule( name = "list", + category = SkylarkModuleCategory.BUILTIN, doc = "A language built-in type to support lists. Example of list literal:<br>" + "<pre class=language-python>x = [1, 2, 3]</pre>" @@ -406,11 +407,10 @@ import javax.annotation.Nullable; public static final MutableList EMPTY = new MutableList(Tuple.EMPTY); } - /** - * An immutable tuple, e.g. in (1, 2, 3) - */ + /** An immutable tuple, e.g. in (1, 2, 3) */ @SkylarkModule( name = "tuple", + category = SkylarkModuleCategory.BUILTIN, doc = "A language built-in type to support tuples. Example of tuple literal:<br>" + "<pre class=language-python>x = (1, 2, 3)</pre>" diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java index 25ef2865e7..bd4be21685 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java @@ -21,6 +21,7 @@ import com.google.devtools.build.lib.collect.nestedset.Order; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; +import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.skylarkinterface.SkylarkValue; import com.google.devtools.build.lib.util.Preconditions; @@ -32,50 +33,52 @@ import java.util.Set; import javax.annotation.Nullable; -/** - * A generic type safe NestedSet wrapper for Skylark. - */ -@SkylarkModule(name = "set", - doc = "A language built-in type that supports sets. " - + "Sets can be created using the <a href=\"globals.html#set\">set</a> function, and " - + "they support the <code>|</code> operator to extend the set with more elements or " - + "to nest other sets inside of it. Examples:<br>" - + "<pre class=language-python>s = set([1, 2])\n" - + "s = s | [3] # s == {1, 2, 3}\n" - + "s = s | set([4, 5]) # s == {1, 2, 3, {4, 5}}\n" - + "other = set([\"a\", \"b\", \"c\"], order=\"compile\")</pre>" - + "Note that in these examples <code>{..}</code> is not a valid literal to create sets. " - + "Sets have a fixed generic type, so <code>set([1]) + [\"a\"]</code> or " - + "<code>set([1]) + set([\"a\"])</code> results in an error.<br>" - + "Elements in a set can neither be mutable or be of type <code>list</code>, " - + "<code>struct</code> or <code>dict</code>.<br>" - + "When aggregating data from providers, sets can take significantly less memory than " - + "other types as they support nesting, that is, their subsets are shared in memory.<br>" - + "Every set has an <code>order</code> parameter which determines the iteration order. " - + "There are four possible values:" - + "<ul><li><code>compile</code>: Defines a left-to-right post-ordering where child " - + "elements come after those of nested sets (parent-last). For example, " - + "<code>{1, 2, 3, {4, 5}}</code> leads to <code>4 5 1 2 3</code>. Left-to-right order " - + "is preserved for both the child elements and the references to nested sets.</li>" - + "<li><code>stable</code>: Same behavior as <code>compile</code>.</li>" - + "<li><code>link</code>: Defines a variation of left-to-right pre-ordering, i.e. " - + "<code>{1, 2, 3, {4, 5}}</code> leads to <code>1 2 3 4 5</code>. " - + "This ordering enforces that elements of the set always come before elements of " - + "nested sets (parent-first), which may lead to situations where left-to-right " - + "order cannot be preserved (<a href=\"https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/collect/nestedset/LinkOrderExpander.java#L56\">Example</a>)." - + "</li>" - + "<li><code>naive_link</code>: Defines \"naive\" left-to-right pre-ordering " - + "(parent-first), i.e. <code>{1, 2, 3, {4, 5}}</code> leads to <code>1 2 3 4 5</code>. " - + "Unlike <code>link</code> ordering, it will sacrifice the parent-first property in " - + "order to uphold left-to-right order in cases where both properties cannot be " - + "guaranteed (<a href=\"https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/collect/nestedset/NaiveLinkOrderExpander.java#L26\">Example</a>)." - + "</li></ul>" - + "Except for <code>stable</code>, the above values are incompatible with each other. " - + "Consequently, two sets can only be merged via the <code>|</code> operator or via " - + "<code>union()</code> if either both sets have the same <code>order</code> or one of " - + "the sets has <code>stable</code> order. In the latter case the iteration order will be " - + "determined by the outer set, thus ignoring the <code>order</code> parameter of " - + "nested sets.") +/** A generic type safe NestedSet wrapper for Skylark. */ +@SkylarkModule( + name = "set", + category = SkylarkModuleCategory.BUILTIN, + doc = + "A language built-in type that supports sets. " + + "Sets can be created using the <a href=\"globals.html#set\">set</a> function, and " + + "they support the <code>|</code> operator to extend the set with more elements or " + + "to nest other sets inside of it. Examples:<br>" + + "<pre class=language-python>s = set([1, 2])\n" + + "s = s | [3] # s == {1, 2, 3}\n" + + "s = s | set([4, 5]) # s == {1, 2, 3, {4, 5}}\n" + + "other = set([\"a\", \"b\", \"c\"], order=\"compile\")</pre>" + + "Note that in these examples <code>{..}</code> is not a valid literal to create sets. " + + "Sets have a fixed generic type, so <code>set([1]) + [\"a\"]</code> or " + + "<code>set([1]) + set([\"a\"])</code> results in an error.<br>" + + "Elements in a set can neither be mutable or be of type <code>list</code>, " + + "<code>struct</code> or <code>dict</code>.<br>" + + "When aggregating data from providers, sets can take significantly less memory than " + + "other types as they support nesting, that is, their subsets are shared in memory.<br>" + + "Every set has an <code>order</code> parameter which determines the iteration order. " + + "There are four possible values:" + + "<ul><li><code>compile</code>: Defines a left-to-right post-ordering where child " + + "elements come after those of nested sets (parent-last). For example, " + + "<code>{1, 2, 3, {4, 5}}</code> leads to <code>4 5 1 2 3</code>. Left-to-right order " + + "is preserved for both the child elements and the references to nested sets.</li>" + + "<li><code>stable</code>: Same behavior as <code>compile</code>.</li>" + + "<li><code>link</code>: Defines a variation of left-to-right pre-ordering, i.e. " + + "<code>{1, 2, 3, {4, 5}}</code> leads to <code>1 2 3 4 5</code>. " + + "This ordering enforces that elements of the set always come before elements of " + + "nested sets (parent-first), which may lead to situations where left-to-right " + + "order cannot be preserved (<a href=\"https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/collect/nestedset/LinkOrderExpander.java#L56\">Example</a>)." + + "</li>" + + "<li><code>naive_link</code>: Defines \"naive\" left-to-right pre-ordering " + + "(parent-first), i.e. <code>{1, 2, 3, {4, 5}}</code> leads to <code>1 2 3 4 5</code>. " + + "Unlike <code>link</code> ordering, it will sacrifice the parent-first property in " + + "order to uphold left-to-right order in cases where both properties cannot be " + + "guaranteed (<a href=\"https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/collect/nestedset/NaiveLinkOrderExpander.java#L26\">Example</a>)." + + "</li></ul>" + + "Except for <code>stable</code>, the above values are incompatible with each other. " + + "Consequently, two sets can only be merged via the <code>|</code> operator or via " + + "<code>union()</code> if either both sets have the same <code>order</code> or one of " + + "the sets has <code>stable</code> order. In the latter case the iteration order will be " + + "determined by the outer set, thus ignoring the <code>order</code> parameter of " + + "nested sets." +) @Immutable public final class SkylarkNestedSet implements Iterable<Object>, SkylarkValue { |