From 34cdae35dba538a5d834b9ae18c4e493bbad878c Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Tue, 28 Jun 2016 16:13:35 +0000 Subject: Reorganize Skylark Reference documentation. -- MOS_MIGRATED_REVID=126081020 --- .../google/devtools/build/docgen/DocgenConsts.java | 2 + .../docgen/SkylarkDocumentationCollector.java | 9 ++- .../docgen/SkylarkDocumentationProcessor.java | 31 ++++++-- .../build/docgen/skylark/SkylarkModuleDoc.java | 12 +-- .../build/docgen/templates/skylark-category.vm | 16 ++++ .../devtools/build/docgen/templates/skylark-nav.vm | 8 +- .../devtools/build/lib/actions/Artifact.java | 2 + .../google/devtools/build/lib/actions/Root.java | 2 + .../devtools/build/lib/analysis/FileProvider.java | 7 +- .../build/lib/analysis/FilesToRunProvider.java | 7 +- .../devtools/build/lib/analysis/Runfiles.java | 7 +- .../lib/analysis/TransitiveInfoCollection.java | 21 ++--- .../lib/analysis/config/BuildConfiguration.java | 2 + .../lib/analysis/config/FragmentCollection.java | 5 +- .../repository/skylark/SkylarkExecutionResult.java | 2 + .../lib/bazel/repository/skylark/SkylarkOS.java | 6 +- .../lib/bazel/repository/skylark/SkylarkPath.java | 6 +- .../skylark/SkylarkRepositoryContext.java | 6 +- .../google/devtools/build/lib/cmdline/Label.java | 18 +++-- .../devtools/build/lib/packages/Attribute.java | 8 +- .../devtools/build/lib/packages/SkylarkAspect.java | 9 ++- .../build/lib/packages/SkylarkNativeModule.java | 16 ++-- .../devtools/build/lib/rules/SkylarkAttr.java | 19 +++-- .../build/lib/rules/SkylarkCommandLine.java | 13 ++-- .../devtools/build/lib/rules/SkylarkFileType.java | 15 ++-- .../build/lib/rules/SkylarkRuleContext.java | 19 +++-- .../rules/android/AndroidSkylarkApiProvider.java | 21 ++--- .../build/lib/rules/apple/AppleConfiguration.java | 11 ++- .../build/lib/rules/apple/DottedVersion.java | 13 ++-- .../devtools/build/lib/rules/apple/Platform.java | 11 ++- .../build/lib/rules/cpp/CcSkylarkApiProvider.java | 15 ++-- .../build/lib/rules/cpp/CppConfiguration.java | 14 ++-- .../rules/java/JavaCompilationInfoProvider.java | 4 +- .../build/lib/rules/java/JavaConfiguration.java | 11 ++- .../build/lib/rules/java/JavaGenJarsProvider.java | 8 +- .../lib/rules/java/JavaRuleOutputJarsProvider.java | 18 +++-- .../lib/rules/java/JavaSkylarkApiProvider.java | 15 ++-- .../google/devtools/build/lib/rules/java/Jvm.java | 14 ++-- .../build/lib/rules/objc/ObjcConfiguration.java | 11 ++- .../build/lib/rules/objc/ObjcProvider.java | 7 +- .../build/lib/skylarkinterface/SkylarkModule.java | 4 + .../skylarkinterface/SkylarkModuleCategory.java | 64 +++++++++++++++ .../devtools/build/lib/syntax/ClassObject.java | 17 ++-- .../devtools/build/lib/syntax/MethodLibrary.java | 6 +- .../devtools/build/lib/syntax/SkylarkDict.java | 6 +- .../devtools/build/lib/syntax/SkylarkList.java | 26 +++---- .../build/lib/syntax/SkylarkNestedSet.java | 91 +++++++++++----------- 47 files changed, 439 insertions(+), 216 deletions(-) create mode 100644 src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm create mode 100644 src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkModuleCategory.java (limited to 'src') 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 f1f710944e..610c15c6dd 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 @@ public class DocgenConsts { "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 854c3ef82a..2ffb83517b 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.JavaSkylarkApiProvider; 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 @@ import java.util.TreeMap; * 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 a178f64e86..edf80dad68 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 @@ package com.google.devtools.build.docgen; 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 final class SkylarkDocumentationProcessor { public static void generateDocumentation(String outputDir, String... clazz) throws IOException, BuildEncyclopediaDocException { Map modules = SkylarkDocumentationCollector.collectModules(clazz); - List 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> modulesByCategory = new HashMap<>(); + for (SkylarkModuleCategory c : SkylarkModuleCategory.values()) { + modulesByCategory.put(c, new ArrayList()); + } + + 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 @@ public final class SkylarkDocumentationProcessor { page.write(skylarkDocPath); } + private static void writeCategoryPage( + SkylarkModuleCategory category, + String outputDir, + Map> 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 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 0e3c42bee6..288eb4084b 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 @@ public final class SkylarkModuleDoc extends SkylarkDoc { private final Map builtinMethodMap; private ArrayList javaMethods; private TreeMap methodMap; - private String title; + private final String title; public SkylarkModuleDoc(SkylarkModule module, Class classObject) { this.module = Preconditions.checkNotNull( @@ -43,7 +43,11 @@ public final class SkylarkModuleDoc extends SkylarkDoc { 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 @@ public final class SkylarkModuleDoc extends SkylarkDoc { 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 0000000000..b635e48e7d --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm @@ -0,0 +1,16 @@ +--- +layout: documentation +title: ${category.title} +--- +

${category.title}

+ +${category.description} + +
+ +
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 54194c0c24..46f5d1bb8d 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) +
  • Builtin Types and Modules
    • +
  • Configuration fragments
    • +
  • Providers
    • +
  • Globals
    • +
  • Native Module
    • -
  • ${module.title}
    • -#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 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 = "

    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.

    " + "

    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, 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; *

    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.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 TO_ARTIFACT = new Function() { 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}. + *

    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}. * - *

    Implementations of build rules should not 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). + *

    Implementations of build rules should not 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 struct with the following fields:" + "

      " + "

    • label

      c1.equals(c2) <=> c1==c2. */ @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 " + "apple, cpp, " + "java, jvm and " + "objc. " 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. * *

      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

        \n" - + "
      • Matches at least one pattern in include.
        • \n" - + "
      • Does not match any of the patterns in exclude " - + "(default []).
      \n" - + "If the exclude_directories argument is enabled (set to 1)," - + " files of type directory will be omitted from the results (default 1).", + + "
    • Matches at least one pattern in include.
      • \n" + + "
    • Does not match any of the patterns in exclude " + + "(default []).
    \n" + + "If the exclude_directories argument is enabled (set to 1)," + + " files of type directory will be omitted from the results (default 1).", 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. * - *

    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. + *

    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 rule 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 attr.*" + + " functions." + ) public static final class Descriptor { private final Attribute.Builder attributeBuilder; private final ImmutableList 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 implementation 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 implementation 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; * *

    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: - * 

    + * non-numeric characters. For example: 
      *   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 they 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:
- * 
    + * present. For example: 
      *   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 {
   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.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 "
+      + "configuration. "
+      + "
    Rule implementations can get them using "
+      + "ctx."
+      + "fragments.[fragment name]"),
+
+  PROVIDER("Providers",
+      "Providers give rules access "
+      + " to information from their dependencies. "
+      + " 
    This section lists providers available on built-in rules. Rule implementation "
+      + " functions can access them via "
+      + "target.[provider name]."
+  ),
+
+  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 struct 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 struct 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:
    "
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:
    "
     + "
    d = {\"a\": 2, \"b\": 5}
    "
     + "Use brackets to access elements:
    "
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
-    extends MutableCollection implements List, 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 extends MutableCollection implements List, 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:
    "
             + "
    x = [1, 2, 3]
    "
@@ -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:
    "
             + "
    x = (1, 2, 3)
    "
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 set function, and "
-        + "they support the | operator to extend the set with more elements or "
-        + "to nest other sets inside of it. Examples:
    "
-        + "
    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\")
    "
-        + "Note that in these examples {..} is not a valid literal to create sets. "
-        + "Sets have a fixed generic type, so set([1]) + [\"a\"] or "
-        + "set([1]) + set([\"a\"]) results in an error.
    "
-        + "Elements in a set can neither be mutable or be of type list, "
-        + "struct or dict.
    "
-        + "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.
    "
-        + "Every set has an order parameter which determines the iteration order. "
-        + "There are four possible values:"
-        + "
    • compile: Defines a left-to-right post-ordering where child "
-        + "elements come after those of nested sets (parent-last). For example, "
-        + "{1, 2, 3, {4, 5}} leads to 4 5 1 2 3. Left-to-right order "
-        + "is preserved for both the child elements and the references to nested sets.
      • "
-        + "
    • stable: Same behavior as compile.
      • "
-        + "
    • link: Defines a variation of left-to-right pre-ordering, i.e. "
-        + "{1, 2, 3, {4, 5}} leads to 1 2 3 4 5. "
-        + "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 (Example)."
-        + "
      • "
-        + "
    • naive_link: Defines \"naive\" left-to-right pre-ordering "
-        + "(parent-first), i.e. {1, 2, 3, {4, 5}} leads to 1 2 3 4 5. "
-        + "Unlike link ordering, it will sacrifice the parent-first property in "
-        + "order to uphold left-to-right order in cases where both properties cannot be "
-        + "guaranteed (Example)."
-        + "
    "
-        + "Except for stable, the above values are incompatible with each other. "
-        + "Consequently, two sets can only be merged via the | operator or via "
-        + "union() if either both sets have the same order or one of "
-        + "the sets has stable order. In the latter case the iteration order will be "
-        + "determined by the outer set, thus ignoring the order 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 set function, and "
+      + "they support the | operator to extend the set with more elements or "
+      + "to nest other sets inside of it. Examples:
    "
+      + "
    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\")
    "
+      + "Note that in these examples {..} is not a valid literal to create sets. "
+      + "Sets have a fixed generic type, so set([1]) + [\"a\"] or "
+      + "set([1]) + set([\"a\"]) results in an error.
    "
+      + "Elements in a set can neither be mutable or be of type list, "
+      + "struct or dict.
    "
+      + "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.
    "
+      + "Every set has an order parameter which determines the iteration order. "
+      + "There are four possible values:"
+      + "
    • compile: Defines a left-to-right post-ordering where child "
+      + "elements come after those of nested sets (parent-last). For example, "
+      + "{1, 2, 3, {4, 5}} leads to 4 5 1 2 3. Left-to-right order "
+      + "is preserved for both the child elements and the references to nested sets.
      • "
+      + "
    • stable: Same behavior as compile.
      • "
+      + "
    • link: Defines a variation of left-to-right pre-ordering, i.e. "
+      + "{1, 2, 3, {4, 5}} leads to 1 2 3 4 5. "
+      + "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 (Example)."
+      + "
      • "
+      + "
    • naive_link: Defines \"naive\" left-to-right pre-ordering "
+      + "(parent-first), i.e. {1, 2, 3, {4, 5}} leads to 1 2 3 4 5. "
+      + "Unlike link ordering, it will sacrifice the parent-first property in "
+      + "order to uphold left-to-right order in cases where both properties cannot be "
+      + "guaranteed (Example)."
+      + "
    "
+      + "Except for stable, the above values are incompatible with each other. "
+      + "Consequently, two sets can only be merged via the | operator or via "
+      + "union() if either both sets have the same order or one of "
+      + "the sets has stable order. In the latter case the iteration order will be "
+      + "determined by the outer set, thus ignoring the order parameter of "
+      + "nested sets."
+)
 @Immutable
 public final class SkylarkNestedSet implements Iterable, SkylarkValue {
 
-- 
cgit v1.2.3