Code/test/javadoc updates for JDK 16 (#1687) (#1690)

Motivation:
In preparation for the next major LTS JDK release 17, we should start
running CI builds for the current latest major release 16.

Modifications:
- Update javadocs which fail the more strict validation
- Update tests that fail due to JDK access restrictions

Result:
Builds pass on JDK 16, CI is ready to run automated builds.

servicetalk-annotations/src/main/java/io/servicetalk/annotations/package-info.java

@@ -13,5 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Common annotations used by ServiceTalk.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.annotations;

servicetalk-buffer-api/src/main/java/io/servicetalk/buffer/api/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * ServiceTalk Buffer APIs.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.buffer.api;
 

servicetalk-client-api-internal/src/main/java/io/servicetalk/client/api/internal/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Internal utilities which leverage the Client API package.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.client.api.internal;
 

servicetalk-client-api-internal/src/main/java/io/servicetalk/client/api/internal/partition/PowerSetPartitionMapFactory.java

@@ -26,6 +26,9 @@
  * A {@link PartitionMapFactory} that generates {@link PowerSetPartitionMap} type objects.
  */
 public final class PowerSetPartitionMapFactory implements PartitionMapFactory {
+    /**
+     * Singleton instance.
+     */
     public static final PartitionMapFactory INSTANCE = new PowerSetPartitionMapFactory();
 
     private PowerSetPartitionMapFactory() {

servicetalk-client-api-internal/src/main/java/io/servicetalk/client/api/internal/partition/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Internal client utilities that support partitioning use cases.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.client.api.internal.partition;
 

servicetalk-client-api/src/main/java/io/servicetalk/client/api/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * API definitions for Client use cases.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.client.api;
 

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Client APIs targeted at partitioned use cases.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.client.api.partition;
 

servicetalk-concurrent-api-internal/src/main/java/io/servicetalk/concurrent/api/internal/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Internal utilities which leverage the concurrent API package.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.api.internal;
 

servicetalk-concurrent-api-test/src/main/java/io/servicetalk/concurrent/api/test/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Utilities that help build tests when interacting with ServiceTalk concurrent APIs.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.api.test;
 

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/DefaultThreadFactory.java

@@ -28,6 +28,9 @@
 public final class DefaultThreadFactory implements ThreadFactory {
 
     private static final AtomicInteger factoryCount = new AtomicInteger();
+    /**
+     * The default prefix used for new thread names.
+     */
     public static final String DEFAULT_NAME_PREFIX = "servicetalk-executor";
 
     private final String namePrefix;

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Executors.java

@@ -94,7 +94,7 @@ public static Executor newCachedThreadExecutor(ThreadFactory threadFactory) {
      * {@link java.util.concurrent.Executor} is an instance of {@link ScheduledExecutorService}.<p>
      * Task execution will not honor cancellations unless passed {@link java.util.concurrent.Executor}
      * is an instance of {@link ExecutorService}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the
@@ -115,7 +115,7 @@ public static Executor from(java.util.concurrent.Executor jdkExecutor) {
      * is an instance of {@link ScheduledExecutorService}.<p>
      * When a running task is cancelled, the thread running it will be interrupted.
      * For overriding this behavior use {@link #from(ExecutorService, boolean)}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the
@@ -134,7 +134,7 @@ public static Executor from(ExecutorService executorService) {
      * Creates a new {@link Executor} from the provided {@link ExecutorService}.
      * Delayed task execution will be delegated to a global scheduler, unless passed {@link ExecutorService}
      * is an instance of {@link ScheduledExecutorService}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the
@@ -155,7 +155,7 @@ public static Executor from(ExecutorService executorService, boolean mayInterrup
      * Creates a new {@link Executor} from the provided {@link ScheduledExecutorService}.
      * When a running task is cancelled, the thread running it will be interrupted.
      * For overriding this behavior use {@link #from(ScheduledExecutorService, boolean)}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the
@@ -172,7 +172,7 @@ public static Executor from(ScheduledExecutorService scheduledExecutorService) {
 
     /**
      * Creates a new {@link Executor} from the provided {@link ScheduledExecutorService}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the
@@ -197,7 +197,7 @@ public static Executor from(ScheduledExecutorService scheduledExecutorService, b
      * For overriding this behavior use {@link #from(java.util.concurrent.Executor, ScheduledExecutorService, boolean)}.
      * Task execution will not honor cancellations unless passed {@link java.util.concurrent.Executor}
      * is an instance of {@link ExecutorService}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the
@@ -221,7 +221,7 @@ public static Executor from(java.util.concurrent.Executor jdkExecutor,
      * schedule delayed tasks.
      * Task execution will not honor cancellations unless passed {@link java.util.concurrent.Executor}
      * is an instance of {@link ExecutorService}.
-     * <h2>Long running tasks</h2>
+     * <p><strong>Long running tasks</strong></p>
      * {@link java.util.concurrent.Executor} implementations are expected to run long running (blocking) tasks which may
      * depend on other tasks submitted to the same {@link java.util.concurrent.Executor} instance.
      * In order to avoid deadlocks, it is generally a good idea to not allow task queuing in the

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Publisher.java

@@ -3228,7 +3228,7 @@ public final <R> CompletionStage<R> toCompletionStage(Supplier<? extends R> resu
      *     {@code -1} to indicate end of stream after emitting all received data.</li>
      * </ul>
      *
-     * <h2>Flow control</h2>
+     * <p><strong>Flow control</strong></p>
      * This operator may pre-fetch may pre-fetch items from {@code this} {@link Publisher} if available to reduce
      * blocking for read operations from the returned {@link InputStream}. In order to increase responsiveness of the
      * {@link InputStream} some amount of buffering may be done. Use {@link #toInputStream(Function, int)} to manage
@@ -3259,7 +3259,7 @@ public final InputStream toInputStream(Function<? super T, byte[]> serializer) {
      *     {@code -1} to indicate end of stream after emitting all received data.</li>
      * </ul>
      *
-     * <h2>Flow control</h2>
+     * <p><strong>Flow control</strong></p>
      * This operator may pre-fetch items from {@code this} {@link Publisher} if available to reduce blocking for read
      * operations from the returned {@link InputStream}. In order to increase responsiveness of the {@link InputStream}
      * some amount of buffering may be done. {@code queueCapacity} can be used to bound this buffer.
@@ -3293,13 +3293,13 @@ public final InputStream toInputStream(Function<? super T, byte[]> serializer, i
      *     {@link NoSuchElementException}. This error will be thrown only after draining all queued data, if any.</li>
      * </ul>
      *
-     * <h2>Flow control</h2>
+     * <p><strong>Flow control</strong></p>
      * This operator may pre-fetch items from {@code this} {@link Publisher} if available to reduce blocking of
      * {@link Iterator#hasNext()} from the returned {@link BlockingIterable}. In order to increase responsiveness of
      * the {@link Iterator} some amount of buffering may be done. Use {@link #toIterable(int)} to manage capacity of
      * this buffer.
      *
-     * <h2>Blocking</h2>
+     * <p><strong>Blocking</strong></p>
      * The returned {@link BlockingIterator} from the returned {@link BlockingIterable} will block on
      * {@link BlockingIterator#hasNext()} and {@link BlockingIterator#next()} if no data is available. This operator may
      * try to reduce this blocking by requesting data ahead of time.
@@ -3330,13 +3330,13 @@ public final BlockingIterable<T> toIterable() {
      *     {@link NoSuchElementException}. This error will be thrown only after draining all queued data, if any.</li>
      * </ul>
      *
-     * <h2>Flow control</h2>
+     * <p><strong>Flow control</strong></p>
      * This operator may pre-fetch items from {@code this} {@link Publisher} if available to reduce blocking of
      * {@link BlockingIterator#hasNext()} from the returned {@link BlockingIterable}. In order to increase
      * responsiveness of the {@link BlockingIterator} some amount of buffering may be done. {@code queueCapacityHint}
      * can be used to bound this buffer.
      *
-     * <h2>Blocking</h2>
+     * <p><strong>Blocking</strong></p>
      * The returned {@link BlockingIterator} from the returned {@link BlockingIterable} will block on
      * {@link BlockingIterator#hasNext()} and {@link BlockingIterator#next()} if no data is available. This operator may
      * try to reduce this blocking by requesting data ahead of time.

servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * ServiceTalk concurrent APIs which follow Reactive Streams semantics.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.api;
 

servicetalk-concurrent-internal/src/main/java/io/servicetalk/concurrent/internal/CancelImmediatelySubscriber.java

@@ -27,6 +27,9 @@
  */
 public final class CancelImmediatelySubscriber implements PublisherSource.Subscriber<Object> {
     private static final Logger LOGGER = LoggerFactory.getLogger(CancelImmediatelySubscriber.class);
+    /**
+     * Singleton instance.
+     */
     public static final CancelImmediatelySubscriber INSTANCE = new CancelImmediatelySubscriber();
 
     private CancelImmediatelySubscriber() {

servicetalk-concurrent-internal/src/main/java/io/servicetalk/concurrent/internal/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Internal utilities used by concurrent packages.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.internal;
 

servicetalk-concurrent-jdkflow/src/main/java/io/servicetalk/concurrent/jdkflow/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Adapters between ServiceTalk's concurrency APIs and the JDK's {@link java.util.concurrent.Flow} API.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.jdkflow;
 

servicetalk-concurrent-reactivestreams/src/main/java/io/servicetalk/concurrent/reactivestreams/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Adapters between Reactive Streams {@link org.reactivestreams.Publisher} and ServiceTalk concurrent APIs.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.reactivestreams;
 

servicetalk-concurrent-test-internal/src/main/java/io/servicetalk/concurrent/test/internal/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Internal concurrent test utilities used by ServiceTalk.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent.test.internal;
 

servicetalk-concurrent/src/main/java/io/servicetalk/concurrent/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * ServiceTalk concurrent common types.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.concurrent;
 

servicetalk-data-jackson-jersey/src/main/java/io/servicetalk/data/jackson/jersey/config/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Configuration for bindings of ServiceTalk's jackson serialization while using the Jersey router.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.data.jackson.jersey.config;
 

servicetalk-data-jackson-jersey/src/main/java/io/servicetalk/data/jackson/jersey/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Bindings of ServiceTalk's jackson serialization while using the Jersey router.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.data.jackson.jersey;
 

servicetalk-data-jackson/src/main/java/io/servicetalk/data/jackson/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Data serialization which depends upon the Jackson library.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.data.jackson;
 

servicetalk-dns-discovery-netty/src/main/java/io/servicetalk/dns/discovery/netty/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * ServiceTalk DNS client exposed as a {@link io.servicetalk.client.api.ServiceDiscoverer}.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.dns.discovery.netty;
 

servicetalk-encoding-api-internal/src/main/java/io/servicetalk/encoding/api/internal/HeaderUtils.java

@@ -29,6 +29,9 @@
 import static java.util.Collections.singletonList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Header utilities to support encoding.
+ */
 public final class HeaderUtils {
 
     private static final List<ContentCodec> NONE_CONTENT_ENCODING_SINGLETON = singletonList(identity());

servicetalk-encoding-api-internal/src/main/java/io/servicetalk/encoding/api/internal/package-info.java

@@ -13,7 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
+/**
+ * Internal utilities that use the encoding API package.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.encoding.api.internal;
 

servicetalk-encoding-api/src/main/java/io/servicetalk/encoding/api/package-info.java

@@ -13,7 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
+/**
+ * Content encoding and compression related APIs.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.encoding.api;
 

servicetalk-gradle-plugin-internal/src/main/groovy/io/servicetalk/gradle/plugin/internal/ServiceTalkLibraryPlugin.groovy

@@ -20,6 +20,8 @@ import org.gradle.api.Project
 import org.gradle.api.plugins.quality.Pmd
 import org.gradle.api.publish.maven.MavenPublication
 import org.gradle.api.publish.maven.tasks.AbstractPublishToMaven
+import org.gradle.external.javadoc.JavadocOptionFileOption
+import org.gradle.external.javadoc.internal.JavadocOptionFileWriterContext
 
 import static io.servicetalk.gradle.plugin.internal.ProjectUtils.addManifestAttributes
 import static io.servicetalk.gradle.plugin.internal.ProjectUtils.addQualityTask
@@ -50,8 +52,6 @@ final class ServiceTalkLibraryPlugin extends ServiceTalkCorePlugin {
   }
 
   private static void applyJavaLibraryPlugin(Project project) {
-
-
     project.configure(project) {
       pluginManager.apply("java-library")
 
@@ -64,8 +64,9 @@ final class ServiceTalkLibraryPlugin extends ServiceTalkCorePlugin {
 
       javadoc {
         options.noQualifiers "all"
-        // -quiet is a workaround for addStringOption(s) being broken: it's ignored as already added in the command by Gradle
-        options.addStringOption("Xwerror", "-quiet")
+        options.addBooleanOption("Xwerror", true)
+        options.addBooleanOption("Xdoclint:all,-missing", true)
+        options.addBooleanOption("protected", true)
       }
 
       def sourcesJar = createSourcesJarTask(project, sourceSets.main)

servicetalk-grpc-protoc/src/main/java/io/servicetalk/grpc/protoc/package-info.java

@@ -13,6 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * ServiceTalk protoc compiler for the gRPC protocol.
+ */
 @ElementsAreNonnullByDefault
 package io.servicetalk.grpc.protoc;