Fix javadocs to allow build to pass in JDK 17 (#4834)

- Added missing javadocs so that javadoc doclint passes against JDK 17 (invoke by Besu gradle build).
- Exclude following packages from javadoc lint:
org.hyperledger.besu.privacy.contracts.generated
org.hyperledger.besu.tests.acceptance.*
- Temporarily exclude ethereum and evm submodule for doc lint checks.
- Run the javadoc task using GitHub actions (use Java 17) to report any javadoc errors during the PR builds
- Updating plugin-api build.gradle with new hash as javadoc comments caused it to change

Signed-off-by: Usman Saleem <usman@usmans.info>

util/src/main/java/org/hyperledger/besu/util/EndianUtils.java

@@ -14,9 +14,17 @@
  */
 package org.hyperledger.besu.util;
 
+/** The Endian utils. */
 public class EndianUtils {
   // next two methods adopted from:
   // https://github.com/bcgit/bc-java/blob/master/core/src/main/java/org/bouncycastle/util/Pack.java
+
+  /**
+   * Long to big endian.
+   *
+   * @param n the n
+   * @return the byte [ ]
+   */
   public static byte[] longToBigEndian(final long n) {
     final byte[] bs = new byte[8];
     intToBigEndian((int) (n >>> 32), bs, 0);
@@ -24,6 +32,13 @@ public class EndianUtils {
     return bs;
   }
 
+  /**
+   * Int to big endian.
+   *
+   * @param n the n
+   * @param bs the bs
+   * @param off the off
+   */
   @SuppressWarnings("MethodInputParametersMustBeFinal")
   public static void intToBigEndian(final int n, final byte[] bs, int off) {
     bs[off] = (byte) (n >>> 24);

util/src/main/java/org/hyperledger/besu/util/ExceptionUtils.java

@@ -16,6 +16,7 @@ package org.hyperledger.besu.util;
 
 import com.google.common.base.Throwables;
 
+/** The Exception utils. */
 public class ExceptionUtils {
 
   private ExceptionUtils() {}

util/src/main/java/org/hyperledger/besu/util/FutureUtils.java

@@ -22,6 +22,7 @@ import java.util.concurrent.CompletionStage;
 import java.util.function.Function;
 import java.util.function.Supplier;
 
+/** The Future utils. */
 public class FutureUtils {
 
   /**
@@ -31,9 +32,9 @@ public class FutureUtils {
    *
    * <p>This is the exceptional equivalent to {@link CompletionStage#thenCompose(Function)}
    *
+   * @param <T> the type of the CompletionStage's result
    * @param future the future to handle results or exceptions from
    * @param errorHandler the function returning a new CompletionStage
-   * @param <T> the type of the CompletionStage's result
    * @return the CompletionStage
    */
   public static <T> CompletableFuture<T> exceptionallyCompose(
@@ -60,9 +61,9 @@ public class FutureUtils {
    * successfully with the same value. When <code>from</code> completes exceptionally, <code>to
    * </code> will be completed exceptionally with the same exception.
    *
+   * @param <T> the type of the success value
    * @param from the CompletionStage to take results and exceptions from
    * @param to the CompletableFuture to propagate results and exceptions to
-   * @param <T> the type of the success value
    */
   public static <T> void propagateResult(
       final CompletionStage<T> from, final CompletableFuture<T> to) {
@@ -87,9 +88,9 @@ public class FutureUtils {
    * <p>If the Supplier throws an exception, the target CompletableFuture will be completed
    * exceptionally with the thrown exception.
    *
+   * @param <T> the type of the success value
    * @param from the Supplier to get the CompletableFuture to take results and exceptions from
    * @param to the CompletableFuture to propagate results and exceptions to
-   * @param <T> the type of the success value
    */
   public static <T> void propagateResult(
       final Supplier<CompletableFuture<T>> from, final CompletableFuture<T> to) {
@@ -104,8 +105,9 @@ public class FutureUtils {
    * Propagates cancellation, and only cancellation, from one future to another.
    *
    * <p>When <code>from</code> is completed with a {@link
-   * java.util.concurrent.CancellationException} {@link java.util.concurrent.Future#cancel(boolean)}
-   * will be called on <code>to</code>, allowing interruption if the future is currently running.
+   * java.util.concurrent.CancellationException}* {@link
+   * java.util.concurrent.Future#cancel(boolean)} will be called on <code>to</code>, allowing
+   * interruption if the future is currently running.
    *
    * @param from the CompletableFuture to take cancellation from
    * @param to the CompletableFuture to propagate cancellation to

util/src/main/java/org/hyperledger/besu/util/IllegalPortException.java

@@ -14,7 +14,13 @@
  */
 package org.hyperledger.besu.util;
 
+/** The Illegal port exception. */
 public class IllegalPortException extends IllegalArgumentException {
+  /**
+   * Instantiates a new Illegal port exception.
+   *
+   * @param message the message
+   */
   IllegalPortException(final String message) {
     super(message);
   }

util/src/main/java/org/hyperledger/besu/util/InvalidConfigurationException.java

@@ -14,7 +14,13 @@
  */
 package org.hyperledger.besu.util;
 
+/** The Invalid configuration exception. */
 public class InvalidConfigurationException extends IllegalArgumentException {
+  /**
+   * Instantiates a new Invalid configuration exception.
+   *
+   * @param message the message
+   */
   public InvalidConfigurationException(final String message) {
     super(message);
   }

util/src/main/java/org/hyperledger/besu/util/LimitedSet.java

@@ -21,8 +21,11 @@ import java.util.Set;
 
 /** Helper that creates a thread-safe set with a maximum capacity. */
 public final class LimitedSet {
+  /** The enum Mode. */
   public enum Mode {
+    /** Drop least recently accessed mode. */
     DROP_LEAST_RECENTLY_ACCESSED,
+    /** Drop oldest element mode. */
     DROP_OLDEST_ELEMENT
   }
 
@@ -31,10 +34,10 @@ public final class LimitedSet {
   /**
    * Creates a limited set of a initial size, maximum size, and eviction mode.
    *
+   * @param <T> The type of object held in the set.
    * @param initialCapacity The initial size to allocate for the set.
    * @param maxSize The maximum number of elements to keep in the set.
    * @param mode A mode that determines which element is evicted when the set exceeds its max size.
-   * @param <T> The type of object held in the set.
    * @return A thread-safe set that will evict elements when the max size is exceeded.
    */
   public static final <T> Set<T> create(

util/src/main/java/org/hyperledger/besu/util/Log4j2ConfiguratorUtil.java

@@ -25,10 +25,17 @@ import org.apache.logging.log4j.util.Strings;
 import org.apache.logging.slf4j.Log4jLoggerFactory;
 import org.slf4j.LoggerFactory;
 
+/** The Log4j2 configurator util. */
 public class Log4j2ConfiguratorUtil {
 
   private Log4j2ConfiguratorUtil() {}
 
+  /**
+   * Sets all levels.
+   *
+   * @param parentLogger the parent logger
+   * @param level the level
+   */
   public static void setAllLevels(final String parentLogger, final Level level) {
     // 1) get logger config
     // 2) if exact match, use it, if not, create it.
@@ -48,10 +55,21 @@ public class Log4j2ConfiguratorUtil {
     }
   }
 
+  /**
+   * Sets Debug level to specified logger.
+   *
+   * @param loggerName the logger name
+   */
   public static void setLevelDebug(final String loggerName) {
     setLevel(loggerName, Level.DEBUG);
   }
 
+  /**
+   * Sets level to specified logger.
+   *
+   * @param loggerName the logger name
+   * @param level the level
+   */
   public static void setLevel(final String loggerName, final Level level) {
     final LoggerContext loggerContext = getLoggerContext();
     if (Strings.isEmpty(loggerName)) {
@@ -92,6 +110,7 @@ public class Log4j2ConfiguratorUtil {
     }
   }
 
+  /** Reconfigure. */
   public static void reconfigure() {
     getLoggerContext().reconfigure();
   }
@@ -102,6 +121,7 @@ public class Log4j2ConfiguratorUtil {
     return (LoggerContext) loggerContexts.iterator().next();
   }
 
+  /** Shutdown. */
   public static void shutdown() {
     getLoggerContext().terminate();
   }

util/src/main/java/org/hyperledger/besu/util/NetworkUtility.java

@@ -29,8 +29,11 @@ import com.google.common.base.Suppliers;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/** The Network utility. */
 public class NetworkUtility {
+  /** The constant INADDR_ANY. */
   public static final String INADDR_ANY = "0.0.0.0";
+  /** The constant INADDR6_ANY. */
   public static final String INADDR6_ANY = "0:0:0:0:0:0:0:0";
 
   private static final Logger LOG = LoggerFactory.getLogger(NetworkUtility.class);
@@ -75,6 +78,13 @@ public class NetworkUtility {
     return port > 0 && port < 65536;
   }
 
+  /**
+   * Url for socket address.
+   *
+   * @param scheme the scheme
+   * @param address the address
+   * @return the url
+   */
   public static String urlForSocketAddress(final String scheme, final InetSocketAddress address) {
     String hostName = address.getHostName();
     if (isUnspecifiedAddress(hostName)) {
@@ -86,6 +96,14 @@ public class NetworkUtility {
     return scheme + "://" + hostName + ":" + address.getPort();
   }
 
+  /**
+   * Is network interface available.
+   *
+   * @param ipAddress the ip address
+   * @return the boolean
+   * @throws SocketException the socket exception
+   * @throws UnknownHostException the unknown host exception
+   */
   public static boolean isNetworkInterfaceAvailable(final String ipAddress)
       throws SocketException, UnknownHostException {
     if (isUnspecifiedAddress(ipAddress)) {
@@ -94,10 +112,22 @@ public class NetworkUtility {
     return NetworkInterface.getByInetAddress(InetAddress.getByName(ipAddress)) != null;
   }
 
+  /**
+   * Is unspecified address.
+   *
+   * @param ipAddress the ip address
+   * @return the boolean
+   */
   public static boolean isUnspecifiedAddress(final String ipAddress) {
     return INADDR_ANY.equals(ipAddress) || INADDR6_ANY.equals(ipAddress);
   }
 
+  /**
+   * Check port.
+   *
+   * @param port the port
+   * @param portTypeName the port type name
+   */
   public static void checkPort(final int port, final String portTypeName) {
     if (!isValidPort(port)) {
       throw new IllegalPortException(
@@ -106,6 +136,12 @@ public class NetworkUtility {
     }
   }
 
+  /**
+   * Is port available for tcp.
+   *
+   * @param port the port
+   * @return the boolean
+   */
   public static boolean isPortAvailableForTcp(final int port) {
     try (final ServerSocket serverSocket = new ServerSocket()) {
       serverSocket.setReuseAddress(true);
@@ -128,6 +164,12 @@ public class NetworkUtility {
     return false;
   }
 
+  /**
+   * Is port available.
+   *
+   * @param port the port
+   * @return the boolean
+   */
   public static boolean isPortAvailable(final int port) {
     return isPortAvailableForTcp(port) && isPortAvailableForUdp(port);
   }

util/src/main/java/org/hyperledger/besu/util/Preconditions.java

@@ -18,9 +18,18 @@ import java.util.function.Function;
 
 import com.google.errorprone.annotations.FormatMethod;
 
+/** The Preconditions. */
 public class Preconditions {
   private Preconditions() {}
 
+  /**
+   * Check guard.
+   *
+   * @param condition the condition
+   * @param exceptionGenerator the exception generator
+   * @param template the template
+   * @param variables the variables
+   */
   @FormatMethod
   public static void checkGuard(
       final boolean condition,

util/src/main/java/org/hyperledger/besu/util/Slf4jLambdaHelper.java

@@ -27,6 +27,13 @@ public class Slf4jLambdaHelper {
 
   private Slf4jLambdaHelper() {}
 
+  /**
+   * Warn lambda.
+   *
+   * @param log the log
+   * @param message the message
+   * @param params the params
+   */
   public static void warnLambda(
       final Logger log, final String message, final Supplier<?>... params) {
     if (log.isWarnEnabled()) {
@@ -34,6 +41,13 @@ public class Slf4jLambdaHelper {
     }
   }
 
+  /**
+   * Info lambda.
+   *
+   * @param log the log
+   * @param message the message
+   * @param params the params
+   */
   public static void infoLambda(
       final Logger log, final String message, final Supplier<?>... params) {
     if (log.isInfoEnabled()) {
@@ -41,6 +55,13 @@ public class Slf4jLambdaHelper {
     }
   }
 
+  /**
+   * Debug lambda.
+   *
+   * @param log the log
+   * @param message the message
+   * @param params the params
+   */
   public static void debugLambda(
       final Logger log, final String message, final Supplier<?>... params) {
     if (log.isDebugEnabled()) {
@@ -48,6 +69,13 @@ public class Slf4jLambdaHelper {
     }
   }
 
+  /**
+   * Trace lambda.
+   *
+   * @param log the log
+   * @param message the message
+   * @param params the params
+   */
   public static void traceLambda(
       final Logger log, final String message, final Supplier<?>... params) {
     if (log.isTraceEnabled()) {

util/src/main/java/org/hyperledger/besu/util/Subscribers.java

@@ -56,15 +56,34 @@ public class Subscribers<T> {
     this.suppressCallbackExceptions = suppressCallbackExceptions;
   }
 
+  /**
+   * None subscribers.
+   *
+   * @param <T> the type parameter
+   * @return the subscribers
+   */
   @SuppressWarnings("unchecked")
   public static <T> Subscribers<T> none() {
     return (Subscribers<T>) NONE;
   }
 
+  /**
+   * Create subscribers.
+   *
+   * @param <T> the type parameter
+   * @return the subscribers
+   */
   public static <T> Subscribers<T> create() {
     return new Subscribers<T>(false);
   }
 
+  /**
+   * Create subscribers.
+   *
+   * @param <T> the type parameter
+   * @param catchCallbackExceptions the catch callback exceptions
+   * @return the subscribers
+   */
   public static <T> Subscribers<T> create(final boolean catchCallbackExceptions) {
     return new Subscribers<T>(catchCallbackExceptions);
   }
@@ -86,7 +105,7 @@ public class Subscribers<T> {
    *
    * @param subscriberId the ID of the subscriber to remove
    * @return <code>true</code> if a subscriber with that ID was found and removed, otherwise <code>
-   *     false</code>
+   *          false</code>
    */
   public boolean unsubscribe(final long subscriberId) {
     return subscribers.remove(subscriberId) != null;

util/src/main/java/org/hyperledger/besu/util/io/RollingFileReader.java

@@ -25,6 +25,7 @@ import java.util.function.BiFunction;
 
 import org.xerial.snappy.Snappy;
 
+/** The Rolling file reader. */
 public class RollingFileReader implements Closeable {
   private final BiFunction<Integer, Boolean, Path> filenameGenerator;
   private final boolean compressed;
@@ -34,6 +35,13 @@ public class RollingFileReader implements Closeable {
   private final RandomAccessFile index;
   private boolean done = false;
 
+  /**
+   * Instantiates a new Rolling file reader.
+   *
+   * @param filenameGenerator the filename generator
+   * @param compressed the compressed
+   * @throws IOException the io exception
+   */
   public RollingFileReader(
       final BiFunction<Integer, Boolean, Path> filenameGenerator, final boolean compressed)
       throws IOException {
@@ -46,6 +54,12 @@ public class RollingFileReader implements Closeable {
     currentPosition = index.readUnsignedShort();
   }
 
+  /**
+   * Read bytes.
+   *
+   * @return the byte [ ]
+   * @throws IOException the io exception
+   */
   public byte[] readBytes() throws IOException {
     byte[] raw;
     try {
@@ -75,6 +89,12 @@ public class RollingFileReader implements Closeable {
     return compressed ? Snappy.uncompress(raw) : raw;
   }
 
+  /**
+   * Seek.
+   *
+   * @param position the position
+   * @throws IOException the io exception
+   */
   public void seek(final long position) throws IOException {
     index.seek(position * 6);
     final int oldFile = fileNumber;
@@ -92,6 +112,11 @@ public class RollingFileReader implements Closeable {
     index.close();
   }
 
+  /**
+   * Is done.
+   *
+   * @return the boolean
+   */
   public boolean isDone() {
     return done;
   }

util/src/main/java/org/hyperledger/besu/util/io/RollingFileWriter.java

@@ -27,6 +27,7 @@ import java.util.function.BiFunction;
 
 import org.xerial.snappy.Snappy;
 
+/** The Rolling file writer. */
 public class RollingFileWriter implements Closeable {
   private static final long MAX_FILE_SIZE = 1 << 30; // 1 GiB max file size
 
@@ -37,6 +38,13 @@ public class RollingFileWriter implements Closeable {
   private FileOutputStream out;
   private final DataOutputStream index;
 
+  /**
+   * Instantiates a new Rolling file writer.
+   *
+   * @param filenameGenerator the filename generator
+   * @param compressed the compressed
+   * @throws FileNotFoundException the file not found exception
+   */
   public RollingFileWriter(
       final BiFunction<Integer, Boolean, Path> filenameGenerator, final boolean compressed)
       throws FileNotFoundException {
@@ -55,10 +63,22 @@ public class RollingFileWriter implements Closeable {
     index = new DataOutputStream(new FileOutputStream(dataFileToIndex(firstOutputFile).toFile()));
   }
 
+  /**
+   * Data file to index path.
+   *
+   * @param dataName the data name
+   * @return the path
+   */
   public static Path dataFileToIndex(final Path dataName) {
     return Path.of(dataName.toString().replaceAll("(.*)[-.]\\d\\d\\d\\d\\.(.)dat", "$1.$2idx"));
   }
 
+  /**
+   * Write bytes.
+   *
+   * @param bytes the bytes
+   * @throws IOException the io exception
+   */
   public void writeBytes(final byte[] bytes) throws IOException {
     final byte[] finalBytes;
     if (compressed) {

util/src/main/java/org/hyperledger/besu/util/log/FramedLogMessage.java

@@ -19,11 +19,18 @@ import java.util.List;
 import com.google.common.base.Splitter;
 import org.apache.commons.lang3.StringUtils;
 
+/** The Framed log message. */
 public class FramedLogMessage {
   private static final int MAX_LINE_LENGTH = 100;
 
   private FramedLogMessage() {}
 
+  /**
+   * Generate log lines as String.
+   *
+   * @param logLines the log lines
+   * @return the string
+   */
   public static String generate(final List<String> logLines) {
     final StringBuilder builder = new StringBuilder("\n");
     appendHeader(builder);
@@ -44,6 +51,12 @@ public class FramedLogMessage {
     return builder.toString();
   }
 
+  /**
+   * Generate logs as centered string.
+   *
+   * @param logLines the log lines
+   * @return the string
+   */
   public static String generateCentered(final List<String> logLines) {
     final StringBuilder builder = new StringBuilder("\n");
     appendHeader(builder);

util/src/main/java/org/hyperledger/besu/util/number/ByteUnits.java

@@ -15,7 +15,9 @@
 
 package org.hyperledger.besu.util.number;
 
+/** The Byte units. */
 public class ByteUnits {
+  /** The constant MEGABYTE. */
   public static final int MEGABYTE = 1 << 20;
 
   private ByteUnits() {}

util/src/main/java/org/hyperledger/besu/util/number/Fraction.java

@@ -19,6 +19,7 @@ import static java.lang.Float.parseFloat;
 
 import java.util.Objects;
 
+/** The Fraction. */
 public class Fraction {
 
   private final float value;
@@ -27,14 +28,31 @@ public class Fraction {
     this.value = value;
   }
 
+  /**
+   * From percentage to fraction.
+   *
+   * @param percentage the percentage
+   * @return the fraction
+   */
   public static Fraction fromPercentage(final int percentage) {
     return fromFloat((float) percentage / 100.0f);
   }
 
+  /**
+   * From percentage to fraction.
+   *
+   * @param percentage the percentage
+   * @return the fraction
+   */
   public static Fraction fromPercentage(final Percentage percentage) {
     return fromFloat(percentage.getValueAsFloat() / 100.0f);
   }
 
+  /**
+   * To percentage.
+   *
+   * @return the percentage
+   */
   public Percentage toPercentage() {
     return Percentage.fromInt((int) (value * 100.0f));
   }
@@ -52,11 +70,22 @@ public class Fraction {
     return fromFloat(parseFloat(str));
   }
 
+  /**
+   * From float to fraction.
+   *
+   * @param val the val
+   * @return the fraction
+   */
   public static Fraction fromFloat(final float val) {
     checkArgument(val > 0.0f && val <= 1.0f);
     return new Fraction(val);
   }
 
+  /**
+   * Gets value.
+   *
+   * @return the value
+   */
   public float getValue() {
     return value;
   }

util/src/main/java/org/hyperledger/besu/util/number/Percentage.java

@@ -19,6 +19,7 @@ import static java.lang.Integer.parseInt;
 
 import java.util.Objects;
 
+/** The Percentage utility. */
 public class Percentage {
 
   private final int value;
@@ -40,15 +41,31 @@ public class Percentage {
     return fromInt(parseInt(str));
   }
 
+  /**
+   * Instantiate percentage.
+   *
+   * @param val the val
+   * @return the percentage
+   */
   public static Percentage fromInt(final int val) {
     checkArgument(val >= 0 && val <= 100);
     return new Percentage(val);
   }
 
+  /**
+   * Gets value.
+   *
+   * @return the value
+   */
   public int getValue() {
     return value;
   }
 
+  /**
+   * Gets value as float.
+   *
+   * @return the value as float
+   */
   public float getValueAsFloat() {
     return value;
   }

util/src/main/java/org/hyperledger/besu/util/number/PositiveNumber.java

@@ -19,6 +19,7 @@ import static java.lang.Integer.parseInt;
 
 import java.util.Objects;
 
+/** The Positive number. */
 public class PositiveNumber {
 
   private final int value;
@@ -42,11 +43,22 @@ public class PositiveNumber {
     return positiveNumber;
   }
 
+  /**
+   * Instantiate positive number from int.
+   *
+   * @param val the val
+   * @return the positive number
+   */
   public static PositiveNumber fromInt(final int val) {
     checkArgument(val > 0);
     return new PositiveNumber(val);
   }
 
+  /**
+   * Gets value.
+   *
+   * @return the value
+   */
   public int getValue() {
     return value;
   }

util/src/main/java/org/hyperledger/besu/util/platform/PlatformDetector.java

@@ -37,6 +37,11 @@ public class PlatformDetector {
   private static String _arch;
   private static String _glibc;
 
+  /**
+   * Gets OS type.
+   *
+   * @return the OS type
+   */
   public static String getOSType() {
     if (_osType == null) {
       detect();
@@ -44,6 +49,11 @@ public class PlatformDetector {
     return _osType;
   }
 
+  /**
+   * Gets OS.
+   *
+   * @return the OS
+   */
   public static String getOS() {
     if (_os == null) {
       detect();
@@ -51,6 +61,11 @@ public class PlatformDetector {
     return _os;
   }
 
+  /**
+   * Gets Arch.
+   *
+   * @return the Arch
+   */
   public static String getArch() {
     if (_arch == null) {
       detect();
@@ -58,6 +73,11 @@ public class PlatformDetector {
     return _arch;
   }
 
+  /**
+   * Gets VM.
+   *
+   * @return the VM
+   */
   public static String getVM() {
     if (_vm == null) {
       detect();
@@ -65,6 +85,11 @@ public class PlatformDetector {
     return _vm;
   }
 
+  /**
+   * Gets Glibc version.
+   *
+   * @return the Glibc version
+   */
   public static String getGlibc() {
     if (_glibc == null) {
       detectGlibc();
@@ -184,6 +209,13 @@ public class PlatformDetector {
     return UNKNOWN;
   }
 
+  /**
+   * Normalize VM version string.
+   *
+   * @param javaVendor the java vendor
+   * @param javaVmName the java vm name
+   * @return the string
+   */
   static String normalizeVM(final String javaVendor, final String javaVmName) {
     if (javaVmName.contains("graalvm") || javaVendor.contains("graalvm")) {
       return "graalvm";
@@ -218,6 +250,12 @@ public class PlatformDetector {
     return "-" + javaVendor + "-" + javaVmName;
   }
 
+  /**
+   * Normalize java version string.
+   *
+   * @param javaVersion the java version
+   * @return the string
+   */
   static String normalizeJavaVersion(final String javaVersion) {
     // These are already normalized.
     return System.getProperty(javaVersion);