Allow package exclusions and inclusions in javadocs (#35)

Author: vinnybod

docs/api.md

@@ -18,7 +18,8 @@ load("@rules_jvm_external//:defs.bzl", "maven_install", "artifact")
 <pre>
 load("@rules_jvm_external//:defs.bzl", "javadoc")
 
-javadoc(<a href="#javadoc-name">name</a>, <a href="#javadoc-deps">deps</a>, <a href="#javadoc-additional_dependencies">additional_dependencies</a>, <a href="#javadoc-doc_deps">doc_deps</a>, <a href="#javadoc-doc_url">doc_url</a>, <a href="#javadoc-excluded_workspaces">excluded_workspaces</a>, <a href="#javadoc-javadocopts">javadocopts</a>)
+javadoc(<a href="#javadoc-name">name</a>, <a href="#javadoc-deps">deps</a>, <a href="#javadoc-additional_dependencies">additional_dependencies</a>, <a href="#javadoc-doc_deps">doc_deps</a>, <a href="#javadoc-doc_resources">doc_resources</a>, <a href="#javadoc-doc_url">doc_url</a>, <a href="#javadoc-excluded_packages">excluded_packages</a>,
+        <a href="#javadoc-excluded_workspaces">excluded_workspaces</a>, <a href="#javadoc-included_packages">included_packages</a>, <a href="#javadoc-javadocopts">javadocopts</a>)
 </pre>
 
 Generate a javadoc from all the `deps`
@@ -32,8 +33,11 @@ Generate a javadoc from all the `deps`
 | <a id="javadoc-deps"></a>deps |  The java libraries to generate javadocs for.<br><br>The source jars of each dep will be used to generate the javadocs. Currently docs for transitive dependencies are not generated.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | required |  |
 | <a id="javadoc-additional_dependencies"></a>additional_dependencies |  Mapping of `Label`s to the excluded workspace names. Note that this must match the values passed to the `pom_file` rule so the `pom.xml` correctly lists these dependencies.   | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional |  `{}`  |
 | <a id="javadoc-doc_deps"></a>doc_deps |  `javadoc` targets referenced by the current target.<br><br>Use this to automatically add appropriate `-linkoffline` javadoc options to resolve references to packages documented by the given javadoc targets that have `url` specified.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
+| <a id="javadoc-doc_resources"></a>doc_resources |  Resources to include in the javadoc jar.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
 | <a id="javadoc-doc_url"></a>doc_url |  The URL at which this documentation will be hosted.<br><br>This information is only used by javadoc targets depending on this target.   | String | optional |  `""`  |
+| <a id="javadoc-excluded_packages"></a>excluded_packages |  A list of packages to exclude from the generated javadoc. Wildcards are supported at the end of the package name. For example, `com.example.*` will exclude all the subpackages of `com.example`, while `com.example` will exclude only the files directly in `com.example`.   | List of strings | optional |  `[]`  |
 | <a id="javadoc-excluded_workspaces"></a>excluded_workspaces |  A list of bazel workspace names to exclude from the generated jar   | List of strings | optional |  `["com_google_protobuf", "protobuf"]`  |
+| <a id="javadoc-included_packages"></a>included_packages |  A list of packages to include in the generated javadoc. Wildcards are supported at the end of the package name. For example, `com.example.*` will include all the subpackages of `com.example`, while `com.example` will include only the files directly in `com.example`.   | List of strings | optional |  `[]`  |
 | <a id="javadoc-javadocopts"></a>javadocopts |  javadoc options. Note sources and classpath are derived from the deps. Any additional options can be passed here. If nothing is passed, a default list of options is used: ["-notimestamp", "-use", "-quiet", "-Xdoclint:-missing", "-encoding", "UTF8"]   | List of strings | optional |  `["-notimestamp", "-use", "-quiet", "-Xdoclint:-missing", "-encoding", "UTF8"]`  |
 
 
@@ -44,8 +48,9 @@ Generate a javadoc from all the `deps`
 <pre>
 load("@rules_jvm_external//:defs.bzl", "java_export")
 
-java_export(<a href="#java_export-name">name</a>, <a href="#java_export-maven_coordinates">maven_coordinates</a>, <a href="#java_export-manifest_entries">manifest_entries</a>, <a href="#java_export-deploy_env">deploy_env</a>, <a href="#java_export-excluded_workspaces">excluded_workspaces</a>,
-            <a href="#java_export-pom_template">pom_template</a>, <a href="#java_export-visibility">visibility</a>, <a href="#java_export-tags">tags</a>, <a href="#java_export-testonly">testonly</a>, <a href="#java_export-classifier_artifacts">classifier_artifacts</a>, <a href="#java_export-kwargs">kwargs</a>)
+java_export(<a href="#java_export-name">name</a>, <a href="#java_export-maven_coordinates">maven_coordinates</a>, <a href="#java_export-manifest_entries">manifest_entries</a>, <a href="#java_export-deploy_env">deploy_env</a>, <a href="#java_export-excluded_workspaces">excluded_workspaces</a>, <a href="#java_export-exclusions">exclusions</a>,
+            <a href="#java_export-pom_template">pom_template</a>, <a href="#java_export-visibility">visibility</a>, <a href="#java_export-tags">tags</a>, <a href="#java_export-testonly">testonly</a>, <a href="#java_export-classifier_artifacts">classifier_artifacts</a>, <a href="#java_export-publish_maven_metadata">publish_maven_metadata</a>,
+            <a href="#java_export-kwargs">kwargs</a>)
 </pre>
 
 Extends `java_library` to allow maven artifacts to be uploaded.
@@ -101,11 +106,13 @@ Generated rules:
 | <a id="java_export-manifest_entries"></a>manifest_entries |  A dict of `String: String` containing additional manifest entry attributes and values.   |  `{}` |
 | <a id="java_export-deploy_env"></a>deploy_env |  A list of labels of Java targets to exclude from the generated jar. [`java_binary`](https://bazel.build/reference/be/java#java_binary) targets are *not* supported.   |  `[]` |
 | <a id="java_export-excluded_workspaces"></a>excluded_workspaces |  A dict of strings representing the workspace names of artifacts that should not be included in the maven jar to a `Label` pointing to the dependency that workspace should be replaced by, or `None` if the exclusion shouldn't be replaced with an extra dependency.   |  `{"com_google_protobuf": None, "protobuf": None}` |
+| <a id="java_export-exclusions"></a>exclusions |  Mapping of target labels to a list of exclusions to be added to the POM file. Each label must correspond to a direct maven dependency of this target. Each exclusion is represented as a `group:artifact` string.   |  `{}` |
 | <a id="java_export-pom_template"></a>pom_template |  The template to be used for the pom.xml file.   |  `None` |
 | <a id="java_export-visibility"></a>visibility |  The visibility of the target   |  `None` |
 | <a id="java_export-tags"></a>tags |  <p align="center"> - </p>   |  `[]` |
 | <a id="java_export-testonly"></a>testonly |  <p align="center"> - </p>   |  `None` |
 | <a id="java_export-classifier_artifacts"></a>classifier_artifacts |  A dict of classifier -> artifact of additional artifacts to publish to Maven.   |  `{}` |
+| <a id="java_export-publish_maven_metadata"></a>publish_maven_metadata |  Whether to publish a maven-metadata.xml and so may contain any valid parameter for that rule.   |  `True` |
 | <a id="java_export-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
 
 

private/rules/java_export.bzl

@@ -94,6 +94,8 @@ def java_export(
     doc_deps = kwargs.pop("doc_deps", [])
     doc_url = kwargs.pop("doc_url", "")
     doc_resources = kwargs.pop("doc_resources", [])
+    doc_excluded_packages = kwargs.pop("doc_excluded_packages", [])
+    doc_included_packages = kwargs.pop("doc_included_packages", [])
     toolchains = kwargs.pop("toolchains", [])
 
     # Construct the java_library we'll export from here.
@@ -123,6 +125,8 @@ def java_export(
         doc_deps = doc_deps,
         doc_url = doc_url,
         doc_resources = doc_resources,
+        doc_excluded_packages = doc_excluded_packages,
+        doc_included_packages = doc_included_packages,
         toolchains = toolchains,
     )
 
@@ -144,6 +148,8 @@ def maven_export(
         doc_deps = [],
         doc_url = "",
         doc_resources = [],
+        doc_excluded_packages = [],
+        doc_included_packages = [],
         publish_maven_metadata = True,
         toolchains = None):
     """
@@ -207,6 +213,12 @@ def maven_export(
       doc_url: The URL at which the generated `javadoc` will be hosted (if not using
         `tags = ["no-javadoc"]`).
       doc_resources: Resources to be included in the javadoc jar.
+      doc_excluded_packages: A list of packages to exclude from the generated javadoc. Wildcards are supported at the
+        end of the package name. For example, `com.example.*` will exclude all the subpackages of `com.example`, while
+        `com.example` will exclude only the files directly in `com.example`
+      doc_included_packages: A list of packages to include in the generated javadoc. Wildcards are supported at the
+        end of the package name. For example, `com.example.*` will include all the subpackages of `com.example`, while
+        `com.example` will include only the files directly in `com.example`
       visibility: The visibility of the target
       publish_maven_metadata: Whether to publish a maven-metadata.xml
       kwargs: These are passed to [`java_library`](https://bazel.build/reference/be/java#java_library),
@@ -278,6 +290,8 @@ def maven_export(
             doc_deps = doc_deps,
             doc_url = doc_url,
             doc_resources = doc_resources,
+            excluded_packages = doc_excluded_packages,
+            included_packages = doc_included_packages,
             excluded_workspaces = excluded_workspaces.keys(),
             additional_dependencies = additional_dependencies,
             visibility = visibility,

private/rules/javadoc.bzl

@@ -25,20 +25,28 @@ def generate_javadoc(
         javadocopts,
         doc_deps,
         doc_resources,
+        excluded_packages,
         output,
         element_list):
     inputs = []
     transitive_inputs = []
     args = ctx.actions.args()
+
     args.add("--out", output)
     args.add("--element-list", element_list)
+
     args.add_all(source_jars, before_each = "--in")
     inputs.extend(source_jars)
+
     args.add_all(ctx.files.doc_resources, before_each = "--resources")
     inputs.extend(ctx.files.doc_resources)
+
     args.add_all(classpath, before_each = "--cp")
     transitive_inputs.append(classpath)
 
+    args.add_all(excluded_packages, before_each = "--exclude-packages")
+    args.add_all(ctx.attr.included_packages, before_each = "--include-packages")
+
     for dep in doc_deps:
         dep_info = dep[_JavadocInfo]
         args.add("-linkoffline")
@@ -90,6 +98,7 @@ def _javadoc_impl(ctx):
         ctx.attr.javadocopts,
         ctx.attr.doc_deps,
         ctx.attr.doc_resources,
+        ctx.attr.excluded_packages,
         jar_file,
         element_list,
     )
@@ -153,6 +162,20 @@ javadoc = rule(
             allow_files = True,
             default = [],
         ),
+        "excluded_packages": attr.string_list(
+            doc = """A list of packages to exclude from the generated javadoc. Wildcards are supported at the end of
+            the package name. For example, `com.example.*` will exclude all the subpackages of `com.example`, while
+            `com.example` will exclude only the files directly in `com.example`.""",
+            allow_empty = True,
+            default = [],
+        ),
+        "included_packages": attr.string_list(
+            doc = """A list of packages to include in the generated javadoc. Wildcards are supported at the end of
+            the package name. For example, `com.example.*` will include all the subpackages of `com.example`, while
+            `com.example` will include only the files directly in `com.example`.""",
+            allow_empty = True,
+            default = [],
+        ),
         "excluded_workspaces": attr.string_list(
             doc = "A list of bazel workspace names to exclude from the generated jar",
             allow_empty = True,

private/rules/kt_jvm_export.bzl

@@ -2,7 +2,7 @@ load("@rules_kotlin//kotlin:jvm.bzl", "kt_jvm_library")
 load(":java_export.bzl", "maven_export")
 load(":maven_project_jar.bzl", "DEFAULT_EXCLUDED_WORKSPACES")
 
-KOTLIN_STDLIB = "@rules_kotlin//kotlin/compiler:kotlin-stdlib"
+KOTLIN_STDLIB = "rules_kotlin"
 
 def kt_jvm_export(
         name,
@@ -70,11 +70,8 @@ def kt_jvm_export(
 
     javadocopts = kwargs.pop("javadocopts", None)
 
-    # ensure that the kotlin-stdlib is included in deploy_env
-    if KOTLIN_STDLIB not in deploy_env:
-        updated_deploy_env = deploy_env + [KOTLIN_STDLIB]
-    else:
-        updated_deploy_env = deploy_env
+    updated_excluded_workspaces = {name: None for name in excluded_workspaces}
+    updated_excluded_workspaces.update({KOTLIN_STDLIB: None})
 
     # Construct the kt_jvm_library we'll export from here.
     kt_jvm_library(
@@ -88,8 +85,8 @@ def kt_jvm_export(
         name = name,
         maven_coordinates = maven_coordinates,
         lib_name = lib_name,
-        deploy_env = updated_deploy_env,
-        excluded_workspaces = excluded_workspaces,
+        deploy_env = deploy_env,
+        excluded_workspaces = updated_excluded_workspaces,
         pom_template = pom_template,
         visibility = visibility,
         tags = tags,

private/tools/java/com/github/bazelbuild/rules_jvm_external/javadoc/BUILD

@@ -1,35 +1,46 @@
 java_library(
-    name = "create_jar_lib",
-    srcs = ["CreateJar.java"],
+    name = "javadoc_lib",
+    srcs = ["JavadocJarMaker.java"],
+    visibility = [
+        "//tests/com/github/bazelbuild/rules_jvm_external/javadoc:__pkg__",
+    ],
     deps = [
+        ":create_jar_lib",
         "//private/tools/java/com/github/bazelbuild/rules_jvm_external",
         "//private/tools/java/com/github/bazelbuild/rules_jvm_external/zip",
     ],
 )
 
 java_binary(
     name = "javadoc",
-    srcs = ["JavadocJarMaker.java"],
     main_class = "com.github.bazelbuild.rules_jvm_external.javadoc.JavadocJarMaker",
     visibility = [
         "//visibility:public",
     ],
+    runtime_deps = [
+        ":javadoc_lib",
+    ],
+)
+
+java_library(
+    name = "create_jar_lib",
+    srcs = ["CreateJar.java"],
+    visibility = [
+        "//tests/com/github/bazelbuild/rules_jvm_external/javadoc:__pkg__",
+    ],
     deps = [
-        ":create_jar_lib",
         "//private/tools/java/com/github/bazelbuild/rules_jvm_external",
         "//private/tools/java/com/github/bazelbuild/rules_jvm_external/zip",
     ],
 )
 
 java_binary(
     name = "create_jar",
-    srcs = ["CreateJar.java"],
     main_class = "com.github.bazelbuild.rules_jvm_external.javadoc.CreateJar",
     visibility = [
         "//visibility:public",
     ],
-    deps = [
-        "//private/tools/java/com/github/bazelbuild/rules_jvm_external",
-        "//private/tools/java/com/github/bazelbuild/rules_jvm_external/zip",
+    runtime_deps = [
+        ":create_jar_lib",
     ],
 )

private/tools/java/com/github/bazelbuild/rules_jvm_external/javadoc/CreateJar.java

@@ -1,7 +1,6 @@
 package com.github.bazelbuild.rules_jvm_external.javadoc;
 
 import com.github.bazelbuild.rules_jvm_external.zip.StableZipEntry;
-
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
@@ -21,10 +20,7 @@ public class CreateJar {
 
   public static void main(String[] args) throws IOException {
     Path out = Paths.get(args[0]);
-    Set<Path> inputs = Stream.of(args)
-        .skip(1)
-        .map(Paths::get)
-        .collect(Collectors.toSet());
+    Set<Path> inputs = Stream.of(args).skip(1).map(Paths::get).collect(Collectors.toSet());
 
     Path tmpDir = Files.createTempDirectory("create-jar-temp");
     tmpDir.toFile().deleteOnExit();
@@ -57,8 +53,8 @@ public static void main(String[] args) throws IOException {
 
   public static void createJar(Path out, Path inputDir) throws IOException {
     try (OutputStream os = Files.newOutputStream(out);
-         ZipOutputStream zos = new ZipOutputStream(os);
-         Stream<Path> walk = Files.walk(inputDir)) {
+        ZipOutputStream zos = new ZipOutputStream(os);
+        Stream<Path> walk = Files.walk(inputDir)) {
 
       walk.sorted(Comparator.naturalOrder())
           .forEachOrdered(
@@ -88,4 +84,4 @@ public static void createJar(Path out, Path inputDir) throws IOException {
               });
     }
   }
-}
+}