Reorganize Skylark Reference documentation.
--
MOS_MIGRATED_REVID=126081020
diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
index f1f7109..610c15c 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -42,6 +42,8 @@
"com/google/devtools/build/docgen/templates/skylark-library.vm";
public static final String SKYLARK_NAV_TEMPLATE =
"com/google/devtools/build/docgen/templates/skylark-nav.vm";
+ public static final String SKYLARK_MODULE_CATEGORY_TEMPLATE =
+ "com/google/devtools/build/docgen/templates/skylark-category.vm";
public static final String VAR_LEFT_PANEL = "LEFT_PANEL";
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
index 854c3ef..2ffb835 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -31,6 +31,7 @@
import com.google.devtools.build.lib.rules.java.Jvm;
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.SkylarkSignature;
import com.google.devtools.build.lib.syntax.FuncallExpression;
import com.google.devtools.build.lib.syntax.MethodLibrary;
@@ -52,8 +53,12 @@
* A helper class that collects Skylark module documentation.
*/
final class SkylarkDocumentationCollector {
- @SkylarkModule(name = "globals",
- doc = "Objects, functions and modules registered in the global environment.")
+ @SkylarkModule(
+ name = "globals",
+ title = "Globals",
+ category = SkylarkModuleCategory.TOP_LEVEL_TYPE,
+ doc = "Objects, functions and modules registered in the global environment."
+ )
private static final class TopLevelModule {}
private SkylarkDocumentationCollector() {}
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
index a178f64..edf80da 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -16,10 +16,12 @@
import com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc;
import com.google.devtools.build.docgen.skylark.SkylarkJavaMethodDoc;
import com.google.devtools.build.docgen.skylark.SkylarkModuleDoc;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
+import java.util.HashMap;
import java.util.List;
import java.util.Map;
@@ -35,22 +37,29 @@
public static void generateDocumentation(String outputDir, String... clazz) throws IOException,
BuildEncyclopediaDocException {
Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules(clazz);
- List<SkylarkModuleDoc> navModules = new ArrayList<>();
// Generate the top level module first in the doc
SkylarkModuleDoc topLevelModule = modules.remove(
SkylarkDocumentationCollector.getTopLevelModule().name());
- topLevelModule.setTitle("Globals");
writePage(outputDir, topLevelModule);
- navModules.add(topLevelModule);
+
+ Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modulesByCategory = new HashMap<>();
+ for (SkylarkModuleCategory c : SkylarkModuleCategory.values()) {
+ modulesByCategory.put(c, new ArrayList<SkylarkModuleDoc>());
+ }
+
+ modulesByCategory.get(topLevelModule.getAnnotation().category()).add(topLevelModule);
for (SkylarkModuleDoc module : modules.values()) {
if (module.getAnnotation().documented()) {
writePage(outputDir, module);
- navModules.add(module);
+ modulesByCategory.get(module.getAnnotation().category()).add(module);
}
}
- writeNavPage(outputDir, navModules);
+ writeCategoryPage(SkylarkModuleCategory.CONFIGURATION_FRAGMENT, outputDir, modulesByCategory);
+ writeCategoryPage(SkylarkModuleCategory.BUILTIN, outputDir, modulesByCategory);
+ writeCategoryPage(SkylarkModuleCategory.PROVIDER, outputDir, modulesByCategory);
+ writeNavPage(outputDir, modulesByCategory.get(SkylarkModuleCategory.TOP_LEVEL_TYPE));
}
private static void writePage(String outputDir, SkylarkModuleDoc module) throws IOException {
@@ -60,6 +69,18 @@
page.write(skylarkDocPath);
}
+ private static void writeCategoryPage(
+ SkylarkModuleCategory category,
+ String outputDir,
+ Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modules) throws IOException {
+ File skylarkDocPath = new File(String.format("%s/skylark-%s.html",
+ outputDir, category.getTemplateIdentifier()));
+ Page page = TemplateEngine.newPage(DocgenConsts.SKYLARK_MODULE_CATEGORY_TEMPLATE);
+ page.add("category", category);
+ page.add("modules", modules.get(category));
+ page.write(skylarkDocPath);
+ }
+
private static void writeNavPage(String outputDir, List<SkylarkModuleDoc> navModules)
throws IOException {
File navFile = new File(outputDir + "/" + "skylark-nav.html");
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
index 0e3c42b..288eb40 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
@@ -34,7 +34,7 @@
private final Map<String, SkylarkBuiltinMethodDoc> builtinMethodMap;
private ArrayList<SkylarkJavaMethodDoc> javaMethods;
private TreeMap<String, SkylarkMethodDoc> methodMap;
- private String title;
+ private final String title;
public SkylarkModuleDoc(SkylarkModule module, Class<?> classObject) {
this.module = Preconditions.checkNotNull(
@@ -43,7 +43,11 @@
this.builtinMethodMap = new TreeMap<>();
this.methodMap = new TreeMap<>();
this.javaMethods = new ArrayList<>();
- this.title = module.name();
+ if (module.title().isEmpty()) {
+ this.title = module.name();
+ } else {
+ this.title = module.title();
+ }
}
@Override
@@ -60,10 +64,6 @@
return title;
}
- public void setTitle(String title) {
- this.title = title;
- }
-
public SkylarkModule getAnnotation() {
return module;
}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm
new file mode 100644
index 0000000..b635e48
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm
@@ -0,0 +1,16 @@
+---
+layout: documentation
+title: ${category.title}
+---
+<h1>${category.title}</h1>
+
+${category.description}
+
+<div class="toc">
+<ul>
+#foreach ($module in $modules)
+
+<li><a href="/docs/skylark/lib/${module.name}.html">${module.title}</a></li>
+#end
+</ul>
+</div>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm
index 54194c0..46f5d1b 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm
@@ -1,4 +1,6 @@
-#foreach ($module in $modules)
+<li><a href="/docs/skylark/lib/skylark-builtin.html">Builtin Types and Modules</a></li>
+<li><a href="/docs/skylark/lib/skylark-configuration-fragment.html">Configuration fragments</a></li>
+<li><a href="/docs/skylark/lib/skylark-provider.html">Providers</a></li>
+<li><a href="/docs/skylark/lib/globals.html">Globals</a></li>
+<li><a href="/docs/skylark/lib/native.html">Native Module</a></li>
-<li><a href="/docs/skylark/lib/${module.name}.html">${module.title}</a></li>
-#end
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 fe03f57..bbea1f5 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.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 @@
*/
@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 b09dfa3..a85e95a 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 @@
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 @@
* 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 0b4dd3b..9d6e4e1 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.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 @@
* <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 35c0b9a..8077a59 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.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 d1f1434..0de1b2d 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.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 @@
* 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 ab533151..6dd8dd7 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 @@
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 0499743..012e720 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.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 @@
* <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 3fdd4c8..fb1f4ad 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.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 @@
*/
// 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 ad2e7b60..d306a52d 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.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 @@
*/
@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 05ba5cd..2c45c8e 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.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 3e29c70..cadadec 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.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 @@
* 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 ec6a353..ad2290a 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.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.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 75d4677..19f346f 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.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.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 7e8cfff..5d4fe22 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.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 @@
}
/**
- * 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 625785d..1a78509 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.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 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 31208ba..190a46b 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 @@
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 @@
/**
* 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 @@
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 7038b43..5b0fd57 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.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 @@
/**
* 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 @@
}
};
- /**
- * 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 8e107b9..7fd5fe4 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.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.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 94ca4c8..6b31fd8 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.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 5c5baba..a956e4d 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.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 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 @@
@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 e64bc92..ed8434d 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.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 @@
})));
}
- /**
- * 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 ebc8c98..c8fe054 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.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 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 ebd22f4..7d97b50 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.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 @@
*
* <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 @@
* 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 @@
*/
@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 7a8b1d1..987c4fd 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 @@
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 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 4f250b7..cd5f642 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.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 9889401..0d5d164 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.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.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 76750e7..7a577ec 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.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 8036b9c..27f7d52 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.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 c676b22..12cd42f 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.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 11d16fd..3cbcf25 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.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 eb6e7fa..6d5f353 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.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 edecece..37271b8 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.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 69596dd..8da579b 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.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 d16f80b..7bf91b8 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.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 @@
* 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 0d9d63d..d6ff235 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 @@
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 0000000..9602556
--- /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 cb13c65..638936d 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.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 @@
*/
@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 37d489f..ad52534 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.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 @@
}
};
- /**
- * 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 8cb1926..254264e 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 @@
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 @@
/**
* 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 5855824..890d16c 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.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 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 @@
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 @@
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 25ef286..bd4be21 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.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 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 {
