[kafka] branch trunk updated: MINOR: Various javadoc fixes (#10272)

[ij...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ijuma pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 0e8a84e  MINOR: Various javadoc fixes (#10272)
0e8a84e is described below

commit 0e8a84e5d7203765240894873fd2896906dfbc2b
Author: Ismael Juma <is...@juma.me.uk>
AuthorDate: Tue Mar 9 06:00:16 2021 -0800

    MINOR: Various javadoc fixes (#10272)
    
    - Use consistent options for `javadoc` and `aggregatedJavadoc`
    - `aggregatedJavadoc` depends on `compileJava`
    - `connect-api` inherits `options.links`
    - `streams` and `streams-test-utils` javadoc exclusions should be more
    specific to avoid unexpected behavior in `aggregatedJavadoc` when the
    javadoc for multiple modules is generated together
    
    Reviewers: Chia-Ping Tsai <ch...@gmail.com>
---
 build.gradle | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/build.gradle b/build.gradle
index be6859b..0ac8841 100644
--- a/build.gradle
+++ b/build.gradle
@@ -92,12 +92,6 @@ allprojects {
     }
   }
 
-  tasks.withType(Javadoc) {
-    // disable the crazy super-strict doclint tool in Java 8
-    // noinspection SpellCheckingInspection
-    options.addStringOption('Xdoclint:none', '-quiet')
-  }
-
 }
 
 ext {
@@ -471,6 +465,14 @@ subprojects {
     options.charSet = 'UTF-8'
     options.docEncoding = 'UTF-8'
     options.encoding = 'UTF-8'
+    // Turn off doclint for now, see https://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html for rationale
+    options.addStringOption('Xdoclint:none', '-quiet')
+
+    // The URL structure was changed to include the locale after Java 8
+    if (JavaVersion.current().isJava11Compatible())
+      options.links "https://docs.oracle.com/en/java/javase/${JavaVersion.current().majorVersion}/docs/api/"
+    else
+      options.links "https://docs.oracle.com/javase/8/docs/api/"
   }
 
   task systemTestLibs(dependsOn: jar)
@@ -1476,7 +1478,7 @@ project(':streams') {
 
   javadoc {
     include "**/org/apache/kafka/streams/**"
-    exclude "**/internals/**"
+    exclude "**/org/apache/kafka/streams/internals/**", "**/org/apache/kafka/streams/**/internals/**"
   }
 
   tasks.create(name: "copyDependantLibs", type: Copy) {
@@ -1614,7 +1616,7 @@ project(':streams:test-utils') {
 
   javadoc {
     include "**/org/apache/kafka/streams/test/**"
-    exclude "**/internals/**"
+    exclude "**/org/apache/kafka/streams/internals/**", "**/org/apache/kafka/streams/**/internals/**"
   }
 
   tasks.create(name: "copyDependantLibs", type: Copy) {
@@ -1941,11 +1943,6 @@ project(':connect:api') {
 
   javadoc {
     include "**/org/apache/kafka/connect/**" // needed for the `aggregatedJavadoc` task
-    // The URL structure was changed to include the locale after Java 8
-    if (JavaVersion.current().isJava11Compatible())
-      options.links "https://docs.oracle.com/en/java/javase/${JavaVersion.current().majorVersion}/docs/api/"
-    else
-      options.links "https://docs.oracle.com/javase/8/docs/api/"
   }
 
   tasks.create(name: "copyDependantLibs", type: Copy) {
@@ -2309,12 +2306,19 @@ project(':connect:mirror-client') {
   }
 }
 
-task aggregatedJavadoc(type: Javadoc) {
+task aggregatedJavadoc(type: Javadoc, dependsOn: compileJava) {
   def projectsWithJavadoc = subprojects.findAll { it.javadoc.enabled }
   source = projectsWithJavadoc.collect { it.sourceSets.main.allJava }
   classpath = files(projectsWithJavadoc.collect { it.sourceSets.main.compileClasspath })
   includes = projectsWithJavadoc.collectMany { it.javadoc.getIncludes() }
   excludes = projectsWithJavadoc.collectMany { it.javadoc.getExcludes() }
+
+  options.charSet = 'UTF-8'
+  options.docEncoding = 'UTF-8'
+  options.encoding = 'UTF-8'
+  // Turn off doclint for now, see https://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html for rationale
+  options.addStringOption('Xdoclint:none', '-quiet')
+
   // The URL structure was changed to include the locale after Java 8
   if (JavaVersion.current().isJava11Compatible())
     options.links "https://docs.oracle.com/en/java/javase/${JavaVersion.current().majorVersion}/docs/api/"