Javadoc improvements

- Javadoc: Add missing comments
- Javadoc: Add missing tags
- Javadoc: Sentences end in a period
- Javadoc: Reduce whitespace

Author: garydgregory

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

@@ -34,8 +34,19 @@
  */
 public enum ApplicationProtocol {
 
-    HTTP_2("h2"), HTTP_1_1("http/1.1");
+    /**
+     * The HTTP/2 application protocol.
+     */
+    HTTP_2("h2"),
 
+    /**
+     * The HTTP/1.1 application protocol.
+     */
+    HTTP_1_1("http/1.1");
+
+    /**
+     * The application protocol ID.
+     */
     public final String id;
 
     ApplicationProtocol(final String id) {

httpcore5/src/main/java/org/apache/hc/core5/annotation/Contract.java

@@ -33,13 +33,21 @@
 import java.lang.annotation.Target;
 
 /**
- * This annotation defines behavioral contract enforced at runtime by instances of annotated classes.
+ * Defines behavioral contract enforced at runtime by instances of annotated classes.
  */
 @Documented
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.CLASS)
 public @interface Contract {
 
+    /**
+     * Gets the threading behavior for annotated type.
+     * <p>
+     * The default value is {@link ThreadingBehavior#UNSAFE}.
+     * </p>
+     *
+     * @return the threading behavior for annotated type.
+     */
     ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
 
 }

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

@@ -57,6 +57,11 @@ public class BasicFuture<T> implements Future<T>, Cancellable {
     private final ReentrantLock lock;
     private final Condition condition;
 
+    /**
+     * Constructs a new instance for a FutureCallback.
+     *
+     * @param callback the FutureCallback, may be {@code null}.
+     */
     public BasicFuture(final FutureCallback<T> callback) {
         super();
         this.callback = callback;

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

@@ -27,7 +27,7 @@
 package org.apache.hc.core5.concurrent;
 
 /**
- * Convenience base class for {@link FutureCallback}s that contribute a result
+ * Abstracts implementations of {@link FutureCallback}s that contribute a result
  * of the operation to another {@link FutureCallback}.
  *
  * @param <T> the future result type of an asynchronous operation.
@@ -37,6 +37,11 @@ public abstract class CallbackContribution<T> implements FutureCallback<T> {
 
     private final FutureCallback<?> callback;
 
+    /**
+     * Constructs a new instance for a FutureCallback.
+     *
+     * @param callback the FutureCallback, may be {@code null}.
+     */
     public CallbackContribution(final FutureCallback<?> callback) {
         this.callback = callback;
     }

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

@@ -36,6 +36,12 @@
  */
 public interface Lookup<I> {
 
+    /**
+     * Looks up a value using a lower-case string ID.
+     *
+     * @param name The lookup name.
+     * @return The matching value.
+     */
     I lookup(String name);
 
 }

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

@@ -43,6 +43,12 @@ public final class RegistryBuilder<I> {
 
     private final Map<String, I> items;
 
+    /**
+     * Creates a new RegistryBuilder.
+     *
+     * @param <I> the type of Registry values.
+     * @return a new RegistryBuilder.
+     */
     public static <I> RegistryBuilder<I> create() {
         return new RegistryBuilder<>();
     }
@@ -52,13 +58,25 @@ public static <I> RegistryBuilder<I> create() {
         this.items = new HashMap<>();
     }
 
+    /**
+     * Registers the given item for the given ID.
+     *
+     * @param id The ID key, converted to lower-case.
+     * @param item The item to register.
+     * @return this instance.
+     */
     public RegistryBuilder<I> register(final String id, final I item) {
         Args.notEmpty(id, "ID");
         Args.notNull(item, "Item");
         items.put(TextUtils.toLowerCase(id), item);
         return this;
     }
 
+    /**
+     * Creates a new Registry with the registered items.
+     *
+     * @return a new Registry with the registered items.
+     */
     public Registry<I> build() {
         return new Registry<>(items);
     }

httpcore5/src/main/java/org/apache/hc/core5/http/impl/bootstrap/AsyncServerBootstrap.java

@@ -59,6 +59,7 @@
 import org.apache.hc.core5.http.nio.support.DefaultAsyncResponseExchangeHandlerFactory;
 import org.apache.hc.core5.http.nio.support.TerminalAsyncServerFilter;
 import org.apache.hc.core5.http.protocol.HttpProcessor;
+import org.apache.hc.core5.http.protocol.LookupRegistry;
 import org.apache.hc.core5.http.protocol.UriPatternType;
 import org.apache.hc.core5.net.InetAddressUtils;
 import org.apache.hc.core5.net.URIAuthority;
@@ -99,13 +100,19 @@ private AsyncServerBootstrap() {
         this.filters = new ArrayList<>();
     }
 
+    /**
+     * Creates a new AsyncServerBootstrap instance.
+     *
+     * @return a new AsyncServerBootstrap instance.
+     */
     public static AsyncServerBootstrap bootstrap() {
         return new AsyncServerBootstrap();
     }
 
     /**
      * Sets canonical name (fully qualified domain name) of the server.
      *
+     * @param canonicalHostName canonical name (fully qualified domain name) of the server.
      * @return this instance.
      */
     public final AsyncServerBootstrap setCanonicalHostName(final String canonicalHostName) {
@@ -116,6 +123,7 @@ public final AsyncServerBootstrap setCanonicalHostName(final String canonicalHos
     /**
      * Sets I/O reactor configuration.
      *
+     * @param ioReactorConfig I/O reactor configuration.
      * @return this instance.
      */
     public final AsyncServerBootstrap setIOReactorConfig(final IOReactorConfig ioReactorConfig) {
@@ -126,6 +134,7 @@ public final AsyncServerBootstrap setIOReactorConfig(final IOReactorConfig ioRea
     /**
      * Sets HTTP/1.1 protocol parameters.
      *
+     * @param http1Config  HTTP/1.1 protocol parameters.
      * @return this instance.
      */
     public final AsyncServerBootstrap setHttp1Config(final Http1Config http1Config) {
@@ -134,8 +143,9 @@ public final AsyncServerBootstrap setHttp1Config(final Http1Config http1Config)
     }
 
     /**
-     * Sets connection configuration.
+     * Sets char coding configuration.
      *
+     * @param charCodingConfig char coding configuration.
      * @return this instance.
      */
     public final AsyncServerBootstrap setCharCodingConfig(final CharCodingConfig charCodingConfig) {
@@ -144,8 +154,9 @@ public final AsyncServerBootstrap setCharCodingConfig(final CharCodingConfig cha
     }
 
     /**
-     * Sets {@link org.apache.hc.core5.http.protocol.HttpProcessor} instance.
+     * Sets {@link HttpProcessor} instance.
      *
+     * @param httpProcessor {@link HttpProcessor} instance.
      * @return this instance.
      */
     public final AsyncServerBootstrap setHttpProcessor(final HttpProcessor httpProcessor) {
@@ -154,8 +165,9 @@ public final AsyncServerBootstrap setHttpProcessor(final HttpProcessor httpProce
     }
 
     /**
-     * Sets {@link org.apache.hc.core5.http.ConnectionReuseStrategy} instance.
+     * Sets {@link ConnectionReuseStrategy} instance.
      *
+     * @param connStrategy {@link ConnectionReuseStrategy} instance.
      * @return this instance.
      */
     public final AsyncServerBootstrap setConnectionReuseStrategy(final ConnectionReuseStrategy connStrategy) {
@@ -166,6 +178,7 @@ public final AsyncServerBootstrap setConnectionReuseStrategy(final ConnectionReu
     /**
      * Sets {@link TlsStrategy} instance.
      *
+     * @param tlsStrategy {@link TlsStrategy} instance.
      * @return this instance.
      */
     public final AsyncServerBootstrap setTlsStrategy(final TlsStrategy tlsStrategy) {
@@ -176,6 +189,7 @@ public final AsyncServerBootstrap setTlsStrategy(final TlsStrategy tlsStrategy)
     /**
      * Sets TLS handshake {@link Timeout}.
      *
+     * @param handshakeTimeout TLS handshake {@link Timeout}.
      * @return this instance.
      */
     public final AsyncServerBootstrap setTlsHandshakeTimeout(final Timeout handshakeTimeout) {
@@ -186,6 +200,7 @@ public final AsyncServerBootstrap setTlsHandshakeTimeout(final Timeout handshake
     /**
      * Sets {@link IOSession} {@link Decorator} instance.
      *
+     * @param ioSessionDecorator {@link IOSession} {@link Decorator} instance.
      * @return this instance.
      */
     public final AsyncServerBootstrap setIOSessionDecorator(final Decorator<IOSession> ioSessionDecorator) {
@@ -196,6 +211,7 @@ public final AsyncServerBootstrap setIOSessionDecorator(final Decorator<IOSessio
     /**
      * Sets {@link Exception} {@link Callback} instance.
      *
+     * @param exceptionCallback {@link Exception} {@link Callback} instance.
      * @return this instance.
      */
     public final AsyncServerBootstrap setExceptionCallback(final Callback<Exception> exceptionCallback) {
@@ -206,6 +222,7 @@ public final AsyncServerBootstrap setExceptionCallback(final Callback<Exception>
     /**
      * Sets {@link IOSessionListener} instance.
      *
+     * @param sessionListener {@link IOSessionListener} instance.
      * @return this instance.
      */
     public final AsyncServerBootstrap setIOSessionListener(final IOSessionListener sessionListener) {
@@ -214,18 +231,22 @@ public final AsyncServerBootstrap setIOSessionListener(final IOSessionListener s
     }
 
     /**
+     * Sets a LookupRegistry for Suppliers of AsyncServerExchangeHandler.
+     *
+     * @param lookupRegistry LookupRegistry for Suppliers of AsyncServerExchangeHandler.
      * @return this instance.
      * @deprecated Use {@link RequestRouter}.
      */
     @Deprecated
-    public final AsyncServerBootstrap setLookupRegistry(final org.apache.hc.core5.http.protocol.LookupRegistry<Supplier<AsyncServerExchangeHandler>> lookupRegistry) {
+    public final AsyncServerBootstrap setLookupRegistry(final LookupRegistry<Supplier<AsyncServerExchangeHandler>> lookupRegistry) {
         this.lookupRegistry = lookupRegistry;
         return this;
     }
 
     /**
      * Sets {@link HttpRequestMapper} instance.
      *
+     * @param requestRouter {@link HttpRequestMapper} instance.
      * @return this instance.
      * @see org.apache.hc.core5.http.impl.routing.RequestRouter
      * @since 5.3
@@ -238,6 +259,7 @@ public final AsyncServerBootstrap setRequestRouter(final HttpRequestMapper<Suppl
     /**
      * Sets {@link Http1StreamListener} instance.
      *
+     * @param streamListener {@link Http1StreamListener} instance.
      * @return this instance.
      * @since 5.0
      */
@@ -250,8 +272,8 @@ public final AsyncServerBootstrap setStreamListener(final Http1StreamListener st
      * Registers the given {@link AsyncServerExchangeHandler} {@link Supplier} as a default handler for URIs
      * matching the given pattern.
      *
-     * @param uriPattern the pattern to register the handler for.
-     * @param supplier the handler supplier.
+     * @param uriPattern the non-null pattern to register the handler for.
+     * @param supplier the non-null handler supplier.
      * @return this instance.
      */
     public final AsyncServerBootstrap register(final String uriPattern, final Supplier<AsyncServerExchangeHandler> supplier) {
@@ -263,11 +285,11 @@ public final AsyncServerBootstrap register(final String uriPattern, final Suppli
 
     /**
      * Registers the given {@link AsyncServerExchangeHandler} {@link Supplier} as a handler for URIs
-     * matching the given host and the pattern.
+     * matching the given host and pattern.
      *
-     * @param hostname the host name
-     * @param uriPattern the pattern to register the handler for.
-     * @param supplier the handler supplier.
+     * @param hostname the non-null host name.
+     * @param uriPattern the non-null pattern to register the handler for.
+     * @param supplier the non-null handler supplier.
      * @return this instance.
      * @since 5.3
      */
@@ -280,9 +302,14 @@ public final AsyncServerBootstrap register(final String hostname, final String u
     }
 
     /**
-     * @deprecated use {@link #register(String, String, Supplier)}.
+     * Registers the given {@link AsyncServerExchangeHandler} {@link Supplier} as a handler for URIs
+     * matching the given host and pattern.
      *
+     * @param hostname the host name.
+     * @param uriPattern the pattern to register the handler for.
+     * @param supplier the handler supplier.
      * @return this instance.
+     * @deprecated use {@link #register(String, String, Supplier)}.
      */
     @Deprecated
     public final AsyncServerBootstrap registerVirtual(final String hostname, final String uriPattern, final Supplier<AsyncServerExchangeHandler> supplier) {
@@ -307,8 +334,9 @@ public final <T> AsyncServerBootstrap register(
 
     /**
      * Registers the given {@link AsyncServerRequestHandler} as a handler for URIs
-     * matching the given host and the pattern.
+     * matching the given host and pattern.
      *
+     * @param <T> the request type.
      * @param hostname the host name
      * @param uriPattern the pattern to register the handler for.
      * @param requestHandler the handler.
@@ -321,6 +349,7 @@ public final <T> AsyncServerBootstrap register(final String hostname, final Stri
     }
 
     /**
+     * @param <T> the request type.
      * @return this instance.
      * @deprecated Use {@link #register(String, String, AsyncServerRequestHandler)}.
      */

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

@@ -42,13 +42,21 @@
  */
 public interface HttpConnectionFactory<T extends HttpConnection> {
 
+    /**
+     * Creates TLS connection with a {@link SSLSocket} layered over a plain {@link Socket}.
+     *
+     * @param socket the plain socket SSL socket has been layered over.
+     * @return a new HttpConnection.
+     * @throws IOException in case of an I/O error.
+     */
     T createConnection(Socket socket) throws IOException;
 
     /**
      * Creates TLS connection with a {@link SSLSocket} layered over a plain {@link Socket}.
      *
      * @param sslSocket the SSL socket. May be {@code null}.
      * @param socket the plain socket SSL socket has been layered over.
+     * @return a new HttpConnection.
      * @throws IOException in case of an I/O error.
      * @since 5.3
      */

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

@@ -35,7 +35,9 @@
 public interface HttpTransportMetrics {
 
     /**
-     * Returns the number of bytes transferred.
+     * Gets the number of bytes transferred.
+     *
+     * @return the number of bytes transferred.
      */
     long getBytesTransferred();