Javadoc improvements

- Fix @link tags.
- Fix @SInCE tag.
- Add missing @throws tags.
- Add missing @param tags for generics.
- Add missing @return tags.
- Sentences end in a period.
- Fix typos.

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/FrameInputBuffer.java

@@ -101,9 +101,8 @@ public void put(final ByteBuffer src) {
      *
      * @param src the source buffer or {@code null} if not available.
      * @param channel the underlying data channel.
-     *
      * @return a complete frame or {@code null} a complete frame cannot be read.
-     *
+     * @throws IOException in case of an I/O error.
      * @since 5.1
      */
     public RawFrame read(final ByteBuffer src, final ReadableByteChannel channel) throws IOException {
@@ -190,6 +189,8 @@ public RawFrame read(final ByteBuffer src, final ReadableByteChannel channel) th
      * Attempts to read a complete frame from the underlying data channel.
      *
      * @param channel the underlying data channel.
+     * @return a complete frame or {@code null} a complete frame cannot be read.
+     * @throws IOException in case of an I/O error.
      */
     public RawFrame read(final ReadableByteChannel channel) throws IOException {
         return read(null, channel);

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/H2MultiplexingRequester.java

@@ -264,6 +264,7 @@ public void cancelled() {
     }
 
     /**
+     * @param <T> The result type returned by the Future's {@code get} method.
      * @since 5.3
      */
     public final <T> Future<T> execute(
@@ -304,6 +305,7 @@ public final <T> Future<T> execute(
     }
 
     /**
+     * @param <T> The result type returned by the Future's {@code get} method.
      * @since 5.3
      */
     public final <T> Future<T> execute(

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/H2RequesterBootstrap.java

@@ -324,6 +324,7 @@ public final H2RequesterBootstrap register(final String hostname, final String u
     }
 
     /**
+     * @return this instance.
      * @deprecated Use {@link #register(String, String, Supplier)}.
      */
     @Deprecated

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/H2ServerBootstrap.java

@@ -317,6 +317,7 @@ public final H2ServerBootstrap registerVirtual(final String hostname, final Stri
      * Registers the given {@link AsyncServerRequestHandler} as a default handler for URIs
      * matching the given pattern.
      *
+     * @param <T> request handler representation.
      * @param uriPattern the pattern to register the handler for.
      * @param requestHandler the handler.
      * @return this instance.
@@ -332,6 +333,7 @@ public final <T> H2ServerBootstrap register(
      * Registers the given {@link AsyncServerRequestHandler} as a handler for URIs
      * matching the given host and the pattern.
      *
+     * @param <T> request handler representation.
      * @param hostname the host name
      * @param uriPattern the pattern to register the handler for.
      * @param requestHandler the handler.
@@ -348,6 +350,7 @@ public final <T> H2ServerBootstrap register(
     }
 
     /**
+     * @param <T> request handler representation.
      * @return this instance.
      * @deprecated Use {@link #register(String, String, Supplier)}.
      */
@@ -361,6 +364,8 @@ public final <T> H2ServerBootstrap registerVirtual(
 
     /**
      * Adds the filter before the filter with the given name.
+     *
+     * @return this instance.
      */
     public final H2ServerBootstrap addFilterBefore(final String existing, final String name, final AsyncFilterHandler filterHandler) {
         Args.notBlank(existing, "Existing");

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/nio/AsyncPingHandler.java

@@ -49,6 +49,8 @@ public interface AsyncPingHandler {
      * Triggered to signal receipt of a ping response message.
      *
      * @param feedback the ping message feedback.
+     * @throws HttpException in case of HTTP protocol violation.
+     * @throws IOException in case of an I/O error.
      */
     void consumeResponse(ByteBuffer feedback) throws HttpException, IOException;
 

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/ssl/H2TlsSupport.java

@@ -68,6 +68,7 @@ public static String[] selectApplicationProtocols(final Object attachment) {
     }
 
     /**
+     * @return the given SSLParameters.
      * @since 5.3
      */
     public static SSLParameters enforceRequirements(

httpcore5-reactive/src/main/java/org/apache/hc/core5/reactive/ReactiveRequestProcessor.java

@@ -54,6 +54,8 @@ public interface ReactiveRequestProcessor {
      * @param context the actual execution context.
      * @param requestBody a reactive stream representing the request body.
      * @param responseBodyCallback a callback to invoke with the response body, if any.
+     * @throws HttpException in case of HTTP protocol violation.
+     * @throws IOException in case of an I/O error.
      */
     void processRequest(
             HttpRequest request,

httpcore5-reactive/src/test/java/org/apache/hc/core5/reactive/BasicDataStreamChannel.java

@@ -36,6 +36,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Writes to a byte stream channel.
+ */
 public class BasicDataStreamChannel implements DataStreamChannel {
 
     private final WritableByteChannel byteChannel;

httpcore5-testing/src/test/java/org/apache/hc/core5/testing/nio/MessageExchangeHandler.java

@@ -38,6 +38,7 @@
 import org.apache.hc.core5.http.protocol.HttpContext;
 
 /**
+ * @param <T> The message body type.
  * @since 5.0
  */
 public abstract class MessageExchangeHandler<T> extends AbstractServerExchangeHandler<Message<HttpRequest, T>> {

httpcore5/src/main/java/org/apache/hc/core5/concurrent/FutureCallback.java

@@ -27,8 +27,7 @@
 package org.apache.hc.core5.concurrent;
 
 /**
- * A callback interface that gets invoked upon completion of
- * a {@link concurrent.Future}.
+ * A callback interface that gets invoked upon completion of a {@link java.util.concurrent.Future}.
  *
  * @param <T> the future result type returned by this callback.
  * @since 4.2

httpcore5/src/main/java/org/apache/hc/core5/http/config/Lookup.java

@@ -29,8 +29,9 @@
 
 
 /**
- * Generic lookup by low-case string ID.
+ * Generic lookup by lower-case string ID.
  *
+ * @param <I> the type of values to lookup.
  * @since 4.3
  */
 public interface Lookup<I> {

httpcore5/src/main/java/org/apache/hc/core5/http/config/Registry.java

@@ -37,6 +37,7 @@
 /**
  * Generic registry of items keyed by low-case string ID.
  *
+ * @param <I> the type of values to lookup.
  * @since 4.3
  */
 @Contract(threading = ThreadingBehavior.SAFE)

httpcore5/src/main/java/org/apache/hc/core5/http/config/RegistryBuilder.java

@@ -36,6 +36,7 @@
 /**
  * Builder for {@link Registry} instances.
  *
+ * @param <I> the type of Registry values.
  * @since 4.3
  */
 public final class RegistryBuilder<I> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/AbstractMessageParser.java

@@ -29,6 +29,7 @@
 
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.InterruptedIOException;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -49,6 +50,7 @@
  * Abstract base class for HTTP message parsers that obtain input from
  * an instance of {@link org.apache.hc.core5.http.io.SessionInputBuffer}.
  *
+ * @param <T> The type of {@link HttpMessage}.
  * @since 4.0
  */
 public abstract class AbstractMessageParser<T extends HttpMessage> implements HttpMessageParser<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/io/AbstractMessageWriter.java

@@ -46,6 +46,7 @@
  * Abstract base class for HTTP message writers that serialize output to
  * an instance of {@link org.apache.hc.core5.http.io.SessionOutputBuffer}.
  *
+ * @param <T> The type of {@link HttpMessage}.
  * @since 4.0
  */
 public abstract class AbstractMessageWriter<T extends HttpMessage> implements HttpMessageWriter<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/AbstractMessageParser.java

@@ -46,6 +46,7 @@
  * Abstract {@link NHttpMessageParser} that serves as a base for all message
  * parser implementations.
  *
+ * @param <T> The type of {@link HttpMessage}.
  * @since 4.0
  */
 public abstract class AbstractMessageParser<T extends HttpMessage> implements NHttpMessageParser<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/AbstractMessageWriter.java

@@ -36,15 +36,16 @@
 import org.apache.hc.core5.http.HttpMessage;
 import org.apache.hc.core5.http.message.BasicLineFormatter;
 import org.apache.hc.core5.http.message.LineFormatter;
-import org.apache.hc.core5.http.nio.SessionOutputBuffer;
 import org.apache.hc.core5.http.nio.NHttpMessageWriter;
+import org.apache.hc.core5.http.nio.SessionOutputBuffer;
 import org.apache.hc.core5.util.Args;
 import org.apache.hc.core5.util.CharArrayBuffer;
 
 /**
  * Abstract {@link NHttpMessageWriter} that serves as a base for all message
  * writer implementations.
  *
+ * @param <T> The type of {@link HttpMessage}.
  * @since 4.0
  */
 public abstract class AbstractMessageWriter<T extends HttpMessage> implements NHttpMessageWriter<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/DefaultHttpRequestParser.java

@@ -44,6 +44,7 @@
 /**
  * Default {@link org.apache.hc.core5.http.nio.NHttpMessageParser} implementation for {@link HttpRequest}s.
  *
+ * @param <T> The type of {@link HttpRequest}.
  * @since 4.1
  */
 public class DefaultHttpRequestParser<T extends HttpRequest> extends AbstractMessageParser<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/DefaultHttpRequestWriter.java

@@ -39,6 +39,7 @@
 /**
  * Default {@link org.apache.hc.core5.http.nio.NHttpMessageWriter} implementation for {@link HttpRequest}s.
  *
+ * @param <T> The type of {@link HttpRequest}.
  * @since 4.1
  */
 public class DefaultHttpRequestWriter<T extends HttpRequest> extends AbstractMessageWriter<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/DefaultHttpResponseParser.java

@@ -39,6 +39,7 @@
 /**
  * Default {@link org.apache.hc.core5.http.nio.NHttpMessageParser} implementation for {@link HttpResponse}s.
  *
+ * @param <T> The type of {@link HttpResponse}.
  * @since 4.1
  */
 public class DefaultHttpResponseParser<T extends HttpResponse> extends AbstractMessageParser<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/impl/nio/DefaultHttpResponseWriter.java

@@ -39,6 +39,7 @@
 /**
  * Default {@link org.apache.hc.core5.http.nio.NHttpMessageWriter} implementation for {@link HttpResponse}s.
  *
+ * @param <T> The type of {@link HttpResponse}.
  * @since 4.1
  */
 public class DefaultHttpResponseWriter<T extends HttpResponse> extends AbstractMessageWriter<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpClientResponseHandler.java

@@ -35,7 +35,7 @@
  * Handler that encapsulates the process of generating a response object
  * from a {@link ClassicHttpResponse}.
  *
- *
+ * @param <T> the type of the response.
  * @since 4.0
  */
 @FunctionalInterface

httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpConnectionFactory.java

@@ -37,6 +37,7 @@
 /**
  * Factory for {@link HttpConnection} instances.
  *
+ * @param <T> The type of {@link HttpConnection}.
  * @since 4.3
  */
 public interface HttpConnectionFactory<T extends HttpConnection> {

httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpMessageParser.java

@@ -36,8 +36,7 @@
 /**
  * Message parser intended to build HTTP message head from an input stream.
  *
- * @param <T>
- *            {@link MessageHeaders} or a subclass
+ * @param <T> The type of {@link MessageHeaders}.
  *
  * @since 4.0
  */

httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpMessageParserFactory.java

@@ -33,6 +33,7 @@
 /**
  * Factory for {@link HttpMessageParser} instances.
  *
+ * @param <T> The type of {@link MessageHeaders}.
  * @since 4.3
  */
 public interface HttpMessageParserFactory<T extends MessageHeaders> {

httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpMessageWriter.java

@@ -36,6 +36,7 @@
 /**
  * Message writer intended to serialize HTTP message head to an output stream.
  *
+ * @param <T> The type of {@link MessageHeaders}.
  * @since 4.0
  */
 public interface HttpMessageWriter<T extends MessageHeaders> {

httpcore5/src/main/java/org/apache/hc/core5/http/io/HttpMessageWriterFactory.java

@@ -32,6 +32,7 @@
 /**
  * Factory for {@link HttpMessageWriter} instances.
  *
+ * @param <T> The type of {@link MessageHeaders}.
  * @since 4.3
  */
 public interface HttpMessageWriterFactory<T extends MessageHeaders> {

httpcore5/src/main/java/org/apache/hc/core5/http/nio/AsyncRequestConsumer.java

@@ -37,7 +37,7 @@
 /**
  * Abstract asynchronous request consumer.
  *
- * @param <T> request representation.
+ * @param <T> the future result type returned for callbacks.
  *
  * @since 5.0
  */

httpcore5/src/main/java/org/apache/hc/core5/http/nio/DataStreamChannel.java

@@ -36,7 +36,7 @@
 import org.apache.hc.core5.http.Header;
 
 /**
- * Abstract byte stream channel
+ * Abstract byte stream channel.
  * <p>
  * Implementations are expected to be thread-safe.
  * </p>

httpcore5/src/main/java/org/apache/hc/core5/http/nio/NHttpMessageWriter.java

@@ -35,6 +35,7 @@
 /**
  * Message writer intended to serialize HTTP message head to a session buffer.
  *
+ * @param <T> The type of {@link MessageHeaders}.
  * @since 4.0
  */
 public interface NHttpMessageWriter<T extends MessageHeaders> {

httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AbstractServerExchangeHandler.java

@@ -52,6 +52,7 @@
 /**
  * Abstract server side message exchange handler.
  *
+ * @param <T> the type of request messages.
  * @since 5.0
  */
 public abstract class AbstractServerExchangeHandler<T> implements AsyncServerExchangeHandler {

httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicClientExchangeHandler.java

@@ -51,6 +51,7 @@
  * of {@link AsyncRequestProducer} to generate request message
  * and {@link AsyncResponseConsumer} to process the response message returned by the server.
  *
+ * @param <T> The result type.
  * @since 5.0
  */
 public final class BasicClientExchangeHandler<T> implements AsyncClientExchangeHandler {

httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicRequestConsumer.java

@@ -49,6 +49,7 @@
  * Basic implementation of {@link AsyncRequestConsumer} that represents the request message as
  * a {@link Message} and relies on a {@link AsyncEntityConsumer} to process request entity stream.
  *
+ * @param <T> The message body type.
  * @since 5.0
  */
 public class BasicRequestConsumer<T> implements AsyncRequestConsumer<Message<HttpRequest, T>> {

httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicResponseConsumer.java

@@ -50,6 +50,7 @@
  * a {@link Message} and relies on a {@link AsyncEntityConsumer} to process response entity
  * stream.
  *
+ * @param <T> The message body type.
  * @since 5.0
  */
 public class BasicResponseConsumer<T> implements AsyncResponseConsumer<Message<HttpResponse, T>> {

httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/BasicServerExchangeHandler.java

@@ -40,6 +40,7 @@
  * Basic {@link AbstractServerExchangeHandler} implementation that delegates
  * request processing and response generation to a {@link AsyncServerRequestHandler}.
  *
+ * @param <T> the type of request messages.
  * @since 5.0
  */
 public class BasicServerExchangeHandler<T> extends AbstractServerExchangeHandler<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/support/AbstractMessageBuilder.java

@@ -38,6 +38,7 @@
 /**
  * Abstract {@link HttpMessage} builder.
  *
+ * @param <T> The message type to build.
  * @since 5.1
  */
 public abstract class AbstractMessageBuilder<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/support/AbstractRequestBuilder.java

@@ -49,6 +49,7 @@
 /**
  * Builder for {@link BasicHttpRequest} instances.
  *
+ * @param <T> The request type to build.
  * @since 5.1
  */
 public abstract class AbstractRequestBuilder<T> extends AbstractMessageBuilder<T> {

httpcore5/src/main/java/org/apache/hc/core5/http/support/AbstractResponseBuilder.java

@@ -34,6 +34,7 @@
 /**
  * Builder for {@link BasicHttpRequest} instances.
  *
+ * @param <T> The response type to build.
  * @since 5.1
  */
 public abstract class AbstractResponseBuilder<T> extends AbstractMessageBuilder<T> {

httpcore5/src/main/java/org/apache/hc/core5/io/IOCallback.java

@@ -32,6 +32,7 @@
 /**
  * Abstract I/O callback.
  *
+ * @param <T> the type of the input to the operation.
  * @since 5.0
  */
 public interface IOCallback<T> {

httpcore5/src/main/java/org/apache/hc/core5/io/SocketSupport.java

@@ -56,7 +56,9 @@ public static <T> SocketOption<T> getExtendedSocketOptionOrNull(final String fie
     }
 
     /**
-     * object can be ServerSocket or Socket
+     * Object can be ServerSocket or Socket.
+     *
+     * @param <T> ServerSocket or Socket.
      */
     public static <T> void setOption(final T object, final String fieldName, final T value) throws IOException {
         try {