Javadoc

- Fix Javadoc warnings
- Add missing Javadoc tags
- Normalize some comments

Author: garydgregory

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

@@ -66,6 +66,10 @@ private enum State {
     private int emptyLineCount;
 
     /**
+     * Constructs a new instance for a subclass.
+     *
+     * @param http1Config HTTP/1.1 protocol parameters.
+     * @param lineParser How to parse lines in an HTTP message.
      * @since 5.3
      */
     public AbstractMessageParser(final Http1Config http1Config, final LineParser lineParser) {
@@ -77,6 +81,10 @@ public AbstractMessageParser(final Http1Config http1Config, final LineParser lin
     }
 
     /**
+     * Constructs a new instance for a subclass.
+     *
+     * @param lineParser How to parse lines in an HTTP message.
+     * @param messageConstraints HTTP/1.1 protocol parameters.
      * @deprecated Use {@link #AbstractMessageParser(Http1Config, LineParser)}
      */
     @Deprecated

httpcore5/src/main/java/org/apache/hc/core5/net/InetAddressUtils.java

@@ -101,6 +101,10 @@ private InetAddressUtils() {
     private static final int MAX_COLON_COUNT = 7;
 
     /**
+     * Tests whether the parameter is a valid IPv4 address
+     *
+     * @param input the address character sequence to check for validity
+     * @return true if the input parameter is a valid IPv4 address
      * @deprecated Use {@link #isIPv4(CharSequence)}
      */
     @Deprecated
@@ -109,7 +113,7 @@ public static boolean isIPv4Address(final String input) {
     }
 
     /**
-     * Checks whether the parameter is a valid IPv4 address
+     * Tests whether the parameter is a valid IPv4 address.
      *
      * @param input the address character sequence to check for validity
      * @return true if the input parameter is a valid IPv4 address
@@ -120,6 +124,10 @@ public static boolean isIPv4(final CharSequence input) {
     }
 
     /**
+     * Tests if an IPv6 address is an IPv4-mapped IPv6 address.
+     *
+     * @param  input the IPv6 address to be checked
+     * @return true if the IPv6 address is an IPv4-mapped IPv6 address, false otherwise.
      * @deprecated Use {@link #isIPv4MappedIPv6(CharSequence)}
      */
     @Deprecated
@@ -128,7 +136,7 @@ public static boolean isIPv4MappedIPv64Address(final String input) {
     }
 
     /**
-     * Check if an IPv6 address is an IPv4-mapped IPv6 address.
+     * Tests if an IPv6 address is an IPv4-mapped IPv6 address.
      *
      * @param  input the IPv6 address to be checked
      * @return true if the IPv6 address is an IPv4-mapped IPv6 address, false otherwise.
@@ -150,6 +158,10 @@ static boolean hasValidIPv6ColonCount(final CharSequence input) {
     }
 
     /**
+     * Tests whether the parameter is a valid standard (non-compressed) IPv6 address
+     *
+     * @param input the address character sequence to check for validity
+     * @return true if the input parameter is a valid standard (non-compressed) IPv6 address
      * @deprecated Use {@link #isIPv6Std(CharSequence)}
      */
     @Deprecated
@@ -158,7 +170,7 @@ public static boolean isIPv6StdAddress(final String input) {
     }
 
     /**
-     * Checks whether the parameter is a valid standard (non-compressed) IPv6 address
+     * Tests whether the parameter is a valid standard (non-compressed) IPv6 address
      *
      * @param input the address character sequence to check for validity
      * @return true if the input parameter is a valid standard (non-compressed) IPv6 address
@@ -169,6 +181,10 @@ public static boolean isIPv6Std(final CharSequence input) {
     }
 
     /**
+     * Tests whether the parameter is a valid compressed IPv6 address
+     *
+     * @param input the address character sequence to check for validity
+     * @return true if the input parameter is a valid compressed IPv6 address
      * @deprecated Use {@link #isIPv6HexCompressed(CharSequence)}
      */
     @Deprecated
@@ -177,7 +193,7 @@ public static boolean isIPv6HexCompressedAddress(final String input) {
     }
 
     /**
-     * Checks whether the parameter is a valid compressed IPv6 address
+     * Tests whether the parameter is a valid compressed IPv6 address
      *
      * @param input the address character sequence to check for validity
      * @return true if the input parameter is a valid compressed IPv6 address
@@ -188,6 +204,10 @@ public static boolean isIPv6HexCompressed(final CharSequence input) {
     }
 
     /**
+     * Tests whether the parameter is a valid IPv6 address (including compressed).
+     *
+     * @param input the address character sequence to check for validity
+     * @return true if the input parameter is a valid standard or compressed IPv6 address
      * @deprecated Use {@link #isIPv6(CharSequence)}
      */
     @Deprecated
@@ -196,7 +216,7 @@ public static boolean isIPv6Address(final String input) {
     }
 
     /**
-     * Checks whether the parameter is a valid IPv6 address (including compressed).
+     * Tests whether the parameter is a valid IPv6 address (including compressed).
      *
      * @param input the address character sequence to check for validity
      * @return true if the input parameter is a valid standard or compressed IPv6 address
@@ -224,6 +244,11 @@ public static boolean isIPv6(final CharSequence input) {
     }
 
     /**
+     * Tests whether the parameter is a valid URL formatted bracketed IPv6 address (including compressed).
+     * This matches only bracketed values e.g. {@code [::1]}.
+     *
+     * @param input the address character sequence to check for validity
+     * @return true if the input parameter is a valid URL-formatted bracketed IPv6 address
      * @deprecated Use {@link #isIPv6URLBracketed(CharSequence)}
      */
     @Deprecated
@@ -232,7 +257,7 @@ public static boolean isIPv6URLBracketedAddress(final String input) {
     }
 
     /**
-     * Checks whether the parameter is a valid URL formatted bracketed IPv6 address (including compressed).
+     * Tests whether the parameter is a valid URL formatted bracketed IPv6 address (including compressed).
      * This matches only bracketed values e.g. {@code [::1]}.
      *
      * @param input the address character sequence to check for validity
@@ -251,6 +276,8 @@ public static boolean isIPv6URLBracketed(final CharSequence input) {
     /**
      * Formats {@link SocketAddress} as text.
      *
+     * @param buffer The target buffer to append.
+     * @param socketAddress The SocketAddress to append to {@code buffer}.
      * @since 5.0
      */
     public static void formatAddress(
@@ -271,8 +298,12 @@ public static void formatAddress(
     }
 
     /**
-     * Returns canonical name (fully qualified domain name) of the localhost.
+     * Gets the canonical name of the local host, a fully qualified domain name.
+     * <p>
+     * This can be {@code "localhost"} or a fully qualified domain name like {@code "host.docker.internal"}.
+     * </p>
      *
+     * @return the canonical name of the local host.
      * @since 5.0
      */
     public static String getCanonicalLocalHostName() {