Javadoc improvements and simple code declutter

- Add missing Javadoc tags
- Remove redundant parentheses in lambdas (reduces cluttter)
- Close HTML tags
- Add missing Javadoc descriptions
- No need to nest else clause (reduces cluttter)
- Use a ternary expression
- Use a single return
- Access static method directly
- use Objects.toString()

Author: garydgregory

httpcore5/src/main/java/org/apache/hc/core5/http/ContentType.java

@@ -259,6 +259,10 @@ public Charset getCharset(final Charset defaultCharset) {
     }
 
     /**
+     * Gets the named parameter's value.
+     *
+     * @param name The parameter name.
+     * @return The parameter value.
      * @since 4.3
      */
     public String getParameter(final String name) {
@@ -380,7 +384,8 @@ private static ContentType create(final String mimeType, final NameValuePair[] p
      *        characters {@code <">, <;>, <,>} reserved by the HTTP specification.
      * @param params parameters.
      * @return content type
-     *
+     * @throws UnsupportedCharsetException If no support for a named Charset is available
+     *         in this instance of the Java virtual machine.
      * @since 4.4
      */
     public static ContentType create(
@@ -487,6 +492,8 @@ public ContentType withCharset(final String charset) {
      *
      * @param params parameters.
      * @return a new instance with this MIME type and the given parameters.
+     * @throws UnsupportedCharsetException If no support for a named Charset is available
+     *         in this instance of the Java virtual machine.
      * @since 4.4
      */
     public ContentType withParameters(

httpcore5/src/main/java/org/apache/hc/core5/http/HttpHost.java

@@ -137,6 +137,7 @@ public HttpHost(final String scheme, final String hostname) {
     /**
      * Creates {@code HttpHost} instance from a string. Text may not contain any blanks.
      *
+     * @throws URISyntaxException Thrown when a string could not be parsed as a URI reference.
      * @since 4.4
      */
     public static HttpHost create(final String s) throws URISyntaxException {

httpcore5/src/main/java/org/apache/hc/core5/http/HttpMessage.java

@@ -41,7 +41,9 @@ public interface HttpMessage extends MessageHeaders {
      * For incoming messages it represents protocol version this message was transmitted with.
      * For outgoing messages it represents a hint what protocol version should be used to transmit
      * the message.
+     * </p>
      *
+     * @param version The protocol version.
      * @since 5.0
      */
     void setVersion(ProtocolVersion version);
@@ -52,7 +54,9 @@ public interface HttpMessage extends MessageHeaders {
      * For incoming messages it represents protocol version this message was transmitted with.
      * For outgoing messages it represents a hint what protocol version should be used to transmit
      * the message.
+     * </p>
      *
+     * @return The protocol version.
      * @since 5.0
      */
     ProtocolVersion getVersion();

httpcore5/src/main/java/org/apache/hc/core5/http/HttpRequest.java

@@ -58,6 +58,7 @@ public interface HttpRequest extends HttpMessage {
     /**
      * Sets URI path of this request message.
      *
+     * @param path The URI path of this request message.
      * @since 5.0
      */
     void setPath(String path);
@@ -66,14 +67,14 @@ public interface HttpRequest extends HttpMessage {
      * Returns scheme of this request message.
      *
      * @return  the scheme or {@code null}.
-     *
      * @since 5.0
      */
     String getScheme();
 
     /**
      * Sets scheme of this request message.
      *
+     * @param scheme The scheme of this request message.
      * @since 5.0
      */
     void setScheme(String scheme);
@@ -82,14 +83,14 @@ public interface HttpRequest extends HttpMessage {
      * Returns authority of this request message.
      *
      * @return  the authority or {@code null}.
-     *
      * @since 5.0
      */
     URIAuthority getAuthority();
 
     /**
      * Sets authority of this request message.
      *
+     * @param authority The authority of this request message.
      * @since 5.0
      */
     void setAuthority(URIAuthority authority);
@@ -99,7 +100,6 @@ public interface HttpRequest extends HttpMessage {
      * Applicable to HTTP/1.1 version or earlier.
      *
      * @return  the request URI.
-     *
      * @since 5.0
      */
     String getRequestUri();
@@ -108,7 +108,7 @@ public interface HttpRequest extends HttpMessage {
      * Returns full request URI of this request message.
      *
      * @return  the request URI.
-     *
+     * @throws URISyntaxException Thrown when a string could not be parsed as a URI reference.
      * @since 5.0
      */
     URI getUri() throws URISyntaxException;
@@ -117,7 +117,6 @@ public interface HttpRequest extends HttpMessage {
      * Sets the full request URI of this request message.
      *
      * @param requestUri the request URI.
-     *
      * @since 5.0
      */
     void setUri(final URI requestUri);

httpcore5/src/main/java/org/apache/hc/core5/http/HttpRequestFactory.java

@@ -32,6 +32,7 @@
 /**
  * A factory for {@link HttpRequest} objects.
  *
+ * @param <T> The type of {@link HttpRequest}.
  * @since 4.0
  */
 public interface HttpRequestFactory<T extends HttpRequest> {

httpcore5/src/main/java/org/apache/hc/core5/http/HttpRequestMapper.java

@@ -33,6 +33,7 @@
  * This class can be used to resolve an object matching a particular {@link HttpRequest}.
  * Usually the mapped object will be a request handler to process the request.
  *
+ * @param <T> The type of HTTP request handler.
  * @since 5.0
  */
 public interface HttpRequestMapper<T> {
@@ -41,8 +42,7 @@ public interface HttpRequestMapper<T> {
      * Resolves a handler matching the given request.
      *
      * @param request the request to map to a handler
-     * @return HTTP request handler or {@code null} if no match
-     * is found.
+     * @return HTTP request handler or {@code null} if no match is found.
      * @throws HttpException in case of an HTTP protocol violation.
      */
     T resolve(HttpRequest request, HttpContext context) throws HttpException;

httpcore5/src/main/java/org/apache/hc/core5/http/HttpResponseFactory.java

@@ -30,6 +30,7 @@
 /**
  * A factory for {@link HttpResponse} objects.
  *
+ * @param <T> The type of {@link HttpResponse}.
  * @since 4.0
  */
 public interface HttpResponseFactory<T extends HttpResponse> {

httpcore5/src/main/java/org/apache/hc/core5/http/Method.java

@@ -32,20 +32,65 @@
 import org.apache.hc.core5.util.Args;
 
 /**
- * Common HTTP methods defined by the HTTP spec.
+ * Common HTTP methods defined by the HTTP specification.
+ * <p>
+ * Each method is:
+ * </p>
+ * <ul>
+ * <li>Either <em>safe</em> or <em>unsafe</em>: An HTTP method is safe if it doesn't change the state of the server. In other words, a method is safe if it's
+ * read-only.</li>
+ * <li>Either <em>idempotent</em> or <em>non-idempotent</em>: An HTTP method is idempotent if making a single request has the same effect as making several
+ * identical requests. All safe methods are also idempotent, but not all idempotent methods are safe. For example, {@code PUT} and {@code DELETE} are both
+ * idempotent but unsafe.</li>
+ * </ul>
  *
  * @since 5.0
  */
 public enum Method {
 
+    /**
+     * The HTTP {@code GET} method is safe and idempotent.
+     */
     GET(true, true),
+
+    /**
+     * The HTTP {@code HEAD} method is safe and idempotent.
+     */
     HEAD(true, true),
+
+    /**
+     * The HTTP {@code POST} method is unsafe and non-idempotent.
+     */
     POST(false, false),
+
+    /**
+     * The HTTP {@code PUT} method is unsafe and idempotent.
+     */
     PUT(false, true),
+
+    /**
+     * The HTTP {@code DELETE} method is unsafe and idempotent.
+     */
     DELETE(false, true),
+
+    /**
+     * The HTTP {@code CONNECT} method is unsafe and non-idempotent.
+     */
     CONNECT(false, false),
+
+    /**
+     * The HTTP {@code TRACE} method is safe and idempotent.
+     */
     TRACE(true, true),
+
+    /**
+     * The HTTP {@code OPTIONS} method is safe and idempotent.
+     */
     OPTIONS(true, true),
+
+    /**
+     * The HTTP {@code PATCH} method is unsafe and non-idempotent.
+     */
     PATCH(false, false);
 
     private final boolean safe;
@@ -56,10 +101,20 @@ public enum Method {
         this.idempotent = idempotent;
     }
 
+    /**
+     * Tests whether this method is safe.
+     *
+     * @return whether this method is safe.
+     */
     public boolean isSafe() {
         return safe;
     }
 
+    /**
+     * Tests whether this method is idempotent.
+     *
+     * @return whether this method is idempotent.
+     */
     public boolean isIdempotent() {
         return idempotent;
     }

httpcore5/src/main/java/org/apache/hc/core5/http/ParseException.java

@@ -39,15 +39,15 @@ public class ParseException extends ProtocolException {
     private final int errorOffset;
 
     /**
-     * Creates a {@link ParseException} without details.
+     * Constructs a new {@link ParseException} without details.
      */
     public ParseException() {
         super();
         this.errorOffset = -1;
     }
 
     /**
-     * Creates a {@link ParseException} with a detail message.
+     * Constructs a new {@link ParseException} with a detail message.
      *
      * @param message the exception detail message, or {@code null}
      */
@@ -57,7 +57,7 @@ public ParseException(final String message) {
     }
 
     /**
-     * Creates a {@link ParseException} with parsing context details.
+     * Constructs a new {@link ParseException} with parsing context details.
      *
      * @since 5.0
      */
@@ -69,7 +69,7 @@ public ParseException(final String description, final CharSequence text, final i
     }
 
     /**
-     * Creates a {@link ParseException} with parsing context details.
+     * Constructs a new {@link ParseException} with parsing context details.
      *
      * @since 5.0
      */

httpcore5/src/main/java/org/apache/hc/core5/http/ProtocolVersionParser.java

@@ -64,7 +64,7 @@ public ProtocolVersion parse(
         final int lowerBound = cursor.getLowerBound();
         final int upperBound = cursor.getUpperBound();
         final String token1 = tokenizer.parseToken(buffer, cursor,
-                delimiterPredicate != null ? (ch) -> delimiterPredicate.test(ch) || FULL_STOP_OR_BLANK.test(ch) : FULL_STOP_OR_BLANK);
+                delimiterPredicate != null ? ch -> delimiterPredicate.test(ch) || FULL_STOP_OR_BLANK.test(ch) : FULL_STOP_OR_BLANK);
         final int major;
         try {
             major = Integer.parseInt(token1);
@@ -80,7 +80,7 @@ public ProtocolVersion parse(
         } else {
             cursor.updatePos(cursor.getPos() + 1);
             final String token2 = tokenizer.parseToken(buffer, cursor,
-                    delimiterPredicate != null ? (ch) -> delimiterPredicate.test(ch) || BLANK.test(ch) : BLANK);
+                    delimiterPredicate != null ? ch -> delimiterPredicate.test(ch) || BLANK.test(ch) : BLANK);
             final int minor;
             try {
                 minor = Integer.parseInt(token2);