Fix javadocs to allow build to pass in JDK 17 (hyperledger#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>

.circleci/config.yml

@@ -197,10 +197,6 @@ jobs:
           name: IntegrationTests
           command: |
             ./gradlew --no-daemon integrationTest
-      - run:
-          name: Javadoc
-          command: |
-            ./gradlew --no-daemon javadoc
       - run:
           name: CompileJmh
           command: |

.github/workflows/checks.yml

@@ -19,4 +19,18 @@ jobs:
           java-version: 11
           cache: gradle
       - name: spotless
-        run: ./gradlew --no-daemon --parallel clean spotlessCheck
+        run: ./gradlew --no-daemon --parallel clean spotlessCheck
+  javadoc_17:
+    runs-on: ubuntu-latest
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+      - name: Set up Java 17
+        uses: actions/setup-java@v2
+        with:
+          distribution: adopt
+          java-version: 17
+          cache: gradle
+      - name: javadoc (JDK 17)
+        run: ./gradlew --no-daemon clean javadoc

besu/src/main/java/org/hyperledger/besu/Besu.java

@@ -28,8 +28,14 @@
 import org.slf4j.LoggerFactory;
 import picocli.CommandLine.RunLast;
 
+/** Besu bootstrap class. */
 public final class Besu {
 
+  /**
+   * The main entrypoint to Besu application
+   *
+   * @param args command line arguments.
+   */
   public static void main(final String... args) {
     final Logger logger = setupLogging();
 

besu/src/main/java/org/hyperledger/besu/BesuInfo.java

@@ -18,6 +18,10 @@
 
 import java.util.Optional;
 
+/**
+ * Represent Besu information such as version, OS etc. Used with --version option and during Besu
+ * start.
+ */
 public final class BesuInfo {
   private static final String CLIENT = "besu";
   private static final String VERSION = BesuInfo.class.getPackage().getImplementationVersion();
@@ -26,10 +30,21 @@ public final class BesuInfo {
 
   private BesuInfo() {}
 
+  /**
+   * Generate Besu version
+   *
+   * @return Besu version in format such as besu/v22.10.3/linux-aarch_64/openjdk-java-11
+   */
   public static String version() {
     return String.format("%s/v%s/%s/%s", CLIENT, VERSION, OS, VM);
   }
 
+  /**
+   * Generate node name including identity.
+   *
+   * @param maybeIdentity optional node identity to include in the version string.
+   * @return Version with optional identity if provided.
+   */
   public static String nodeName(final Optional<String> maybeIdentity) {
     return maybeIdentity
         .map(identity -> String.format("%s/%s/v%s/%s/%s", CLIENT, identity, VERSION, OS, VM))

besu/src/main/java/org/hyperledger/besu/Runner.java

@@ -51,6 +51,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/** The Runner controls various Besu services lifecycle. */
 public class Runner implements AutoCloseable {
 
   private static final Logger LOG = LoggerFactory.getLogger(Runner.class);
@@ -77,6 +78,26 @@ public class Runner implements AutoCloseable {
   private final Optional<AutoTransactionLogBloomCachingService>
       autoTransactionLogBloomCachingService;
 
+  /**
+   * Instantiates a new Runner.
+   *
+   * @param vertx the vertx
+   * @param networkRunner the network runner
+   * @param natService the nat service
+   * @param jsonRpc the json rpc
+   * @param engineJsonRpc the engine json rpc
+   * @param graphQLHttp the graph ql http
+   * @param webSocketRpc the web socket rpc
+   * @param ipcJsonRpc the ipc json rpc
+   * @param stratumServer the stratum server
+   * @param metrics the metrics
+   * @param ethStatsService the eth stats service
+   * @param besuController the besu controller
+   * @param dataDir the data dir
+   * @param pidPath the pid path
+   * @param transactionLogBloomCacher the transaction log bloom cacher
+   * @param blockchain the blockchain
+   */
   Runner(
       final Vertx vertx,
       final NetworkRunner networkRunner,
@@ -115,6 +136,7 @@ public class Runner implements AutoCloseable {
         new TransactionPoolEvictionService(vertx, besuController.getTransactionPool());
   }
 
+  /** Start external services. */
   public void startExternalServices() {
     LOG.info("Starting external services ... ");
     metrics.ifPresent(service -> waitForServiceToStart("metrics", service.start()));
@@ -132,6 +154,7 @@ public void startExternalServices() {
     ethStatsService.ifPresent(EthStatsService::start);
   }
 
+  /** Start ethereum main loop. */
   public void startEthereumMainLoop() {
     try {
       LOG.info("Starting Ethereum main loop ... ");
@@ -154,6 +177,7 @@ public void startEthereumMainLoop() {
     }
   }
 
+  /** Stop services. */
   public void stop() {
     transactionPoolEvictionService.stop();
     jsonRpc.ifPresent(service -> waitForServiceToStop("jsonRpc", service.stop()));
@@ -184,6 +208,7 @@ public void stop() {
     shutdown.countDown();
   }
 
+  /** Await stop. */
   public void awaitStop() {
     try {
       shutdown.await();
@@ -328,22 +353,47 @@ private void writePidFile() {
         });
   }
 
+  /**
+   * Gets json rpc port.
+   *
+   * @return the json rpc port
+   */
   public Optional<Integer> getJsonRpcPort() {
     return jsonRpc.map(service -> service.socketAddress().getPort());
   }
 
+  /**
+   * Gets engine json rpc port.
+   *
+   * @return the engine json rpc port
+   */
   public Optional<Integer> getEngineJsonRpcPort() {
     return engineJsonRpc.map(service -> service.socketAddress().getPort());
   }
 
+  /**
+   * Gets GraphQl http port.
+   *
+   * @return the graph ql http port
+   */
   public Optional<Integer> getGraphQLHttpPort() {
     return graphQLHttp.map(service -> service.socketAddress().getPort());
   }
 
+  /**
+   * Gets web socket port.
+   *
+   * @return the web socket port
+   */
   public Optional<Integer> getWebSocketPort() {
     return webSocketRpc.map(service -> service.socketAddress().getPort());
   }
 
+  /**
+   * Gets metrics port.
+   *
+   * @return the metrics port
+   */
   public Optional<Integer> getMetricsPort() {
     if (metrics.isPresent()) {
       return metrics.get().getPort();
@@ -352,13 +402,23 @@ public Optional<Integer> getMetricsPort() {
     }
   }
 
+  /**
+   * Gets local enode.
+   *
+   * @return the local enode
+   */
   @VisibleForTesting
   Optional<EnodeURL> getLocalEnode() {
     return networkRunner.getNetwork().getLocalEnode();
   }
 
   @FunctionalInterface
   private interface SynchronousShutdown {
+    /**
+     * Await for shutdown.
+     *
+     * @throws InterruptedException the interrupted exception
+     */
     void await() throws InterruptedException;
   }