HDDS-11484. Add check for javadoc correctness

.github/workflows/ci.yml

@@ -222,6 +222,41 @@ jobs:
         env:
           OZONE_WITH_COVERAGE: false
           DEVELOCITY_ACCESS_KEY: ${{ secrets.GE_ACCESS_TOKEN }}
+  javadoc:
+    needs:
+      - build-info
+    runs-on: ubuntu-20.04
+    timeout-minutes: 30
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.build-info.outputs.sha }}
+      - name: Cache for maven dependencies
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            ~/.m2/repository/*/*/*
+            !~/.m2/repository/org/apache/ozone
+          key: maven-repo-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            maven-repo-
+      - name: Download Ratis repo
+        if: ${{ inputs.ratis_args != '' }}
+        uses: actions/download-artifact@v4
+        with:
+          name: ratis-jars
+          path: |
+            ~/.m2/repository/org/apache/ratis
+      - name: Setup java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: 11
+      - name: Run a full build with javadocs generation
+        run: hadoop-ozone/dev-support/checks/build.sh -Pdocs -Dmaven.javadoc.skip=false -Dskip.npx -Dskip.installnpx
+        env:
+          DEVELOCITY_ACCESS_KEY: ${{ secrets.GE_ACCESS_TOKEN }}
   basic:
     needs:
       - build-info

hadoop-hdds/client/src/main/java/org/apache/hadoop/hdds/scm/storage/BlockDataStreamOutput.java

@@ -364,7 +364,6 @@ public void writeOnRetry(long len) throws IOException {
    * it is a no op.
    * @param bufferFull flag indicating whether bufferFull condition is hit or
    *              its called as part flush/close
-   * @return minimum commit index replicated to all nodes
    * @throws IOException IOException in case watch gets timed out
    */
   public void watchForCommit(boolean bufferFull) throws IOException {

hadoop-hdds/client/src/main/java/org/apache/hadoop/hdds/scm/storage/ExtendedInputStream.java

@@ -75,7 +75,7 @@ public synchronized int read(ByteBuffer byteBuffer) throws IOException {
    * readWithStrategy implementation, as it will never be called by the tests.
    *
    * @param strategy
-   * @return
+   * @return {@code int}
    * @throws IOException
    */
   protected abstract int readWithStrategy(ByteReaderStrategy strategy) throws

hadoop-hdds/client/src/main/java/org/apache/hadoop/ozone/client/io/BlockInputStreamFactory.java

@@ -43,7 +43,6 @@ public interface BlockInputStreamFactory {
    * @param blockInfo The blockInfo representing the block.
    * @param pipeline The pipeline to be used for reading the block
    * @param token The block Access Token
-   * @param verifyChecksum Whether to verify checksums or not.
    * @param xceiverFactory Factory to create the xceiver in the client
    * @param refreshFunction Function to refresh the block location if needed
    * @return BlockExtendedInputStream of the correct type.

hadoop-hdds/client/src/main/java/org/apache/hadoop/ozone/client/io/BlockInputStreamFactoryImpl.java

@@ -71,7 +71,6 @@ public BlockInputStreamFactoryImpl(ByteBufferPool byteBufferPool,
    * @param blockInfo The blockInfo representing the block.
    * @param pipeline The pipeline to be used for reading the block
    * @param token The block Access Token
-   * @param verifyChecksum Whether to verify checksums or not.
    * @param xceiverFactory Factory to create the xceiver in the client
    * @param refreshFunction Function to refresh the pipeline if needed
    * @return BlockExtendedInputStream of the correct type.

hadoop-hdds/client/src/main/java/org/apache/hadoop/ozone/client/io/ECBlockInputStream.java

@@ -152,7 +152,7 @@ protected int calculateExpectedDataBlocks(ECReplicationConfig rConfig) {
    * Using the current position, returns the index of the blockStream we should
    * be reading from. This is the index in the internal array holding the
    * stream reference. The block group index will be one greater than this.
-   * @return
+   * @return {@code int}
    */
   protected int currentStreamIndex() {
     return (int)((position / ecChunkSize) % repConfig.getData());
@@ -206,7 +206,7 @@ protected BlockExtendedInputStream getOrOpenStream(int locationIndex) throws IOE
    * to the replicaIndex given based on the EC pipeline fetched from SCM.
    * @param replicaIndex
    * @param refreshFunc
-   * @return
+   * @return {@code Function<BlockID, BlockLocationInfo>}
    */
   protected Function<BlockID, BlockLocationInfo> ecPipelineRefreshFunction(
       int replicaIndex, Function<BlockID, BlockLocationInfo> refreshFunc) {
@@ -241,7 +241,7 @@ protected Function<BlockID, BlockLocationInfo> ecPipelineRefreshFunction(
    * potentially partial last stripe. Note that the internal block index is
    * numbered starting from 1.
    * @param index - Index number of the internal block, starting from 1
-   * @return
+   * @return {@code long}
    */
   protected long internalBlockLength(int index) {
     long lastStripe = blockInfo.getLength() % stripeSize;
@@ -344,7 +344,7 @@ protected boolean shouldRetryFailedRead(int failedIndex) {
    * strategy buffer. This call may read from several internal BlockInputStreams
    * if there is sufficient space in the buffer.
    * @param strategy
-   * @return
+   * @return {@code int}
    * @throws IOException
    */
   @Override
@@ -409,7 +409,7 @@ protected void seekStreamIfNecessary(BlockExtendedInputStream stream,
    * group length.
    * @param stream Stream to read from
    * @param strategy The ReaderStrategy to read data into
-   * @return
+   * @return {@code int}
    * @throws IOException
    */
   private int readFromStream(BlockExtendedInputStream stream,

hadoop-hdds/client/src/main/java/org/apache/hadoop/ozone/client/io/ECBlockInputStreamFactory.java

@@ -45,7 +45,6 @@ public interface ECBlockInputStreamFactory {
    *                        know are bad and should not be used.
    * @param repConfig The replication Config
    * @param blockInfo The blockInfo representing the block.
-   * @param verifyChecksum Whether to verify checksums or not.
    * @param xceiverFactory Factory to create the xceiver in the client
    * @param refreshFunction Function to refresh the block location if needed
    * @return BlockExtendedInputStream of the correct type.

hadoop-hdds/client/src/main/java/org/apache/hadoop/ozone/client/io/ECBlockInputStreamFactoryImpl.java

@@ -68,7 +68,6 @@ private ECBlockInputStreamFactoryImpl(BlockInputStreamFactory streamFactory,
    *                        know are bad and should not be used.
    * @param repConfig The replication Config
    * @param blockInfo The blockInfo representing the block.
-   * @param verifyChecksum Whether to verify checksums or not.
    * @param xceiverFactory Factory to create the xceiver in the client
    * @param refreshFunction Function to refresh the pipeline if needed
    * @return BlockExtendedInputStream of the correct type.

hadoop-hdds/client/src/main/java/org/apache/hadoop/ozone/client/io/ECBlockReconstructedStripeInputStream.java

@@ -85,7 +85,7 @@
  * Parity elements long. Missing or not needed elements should be set to null
  * in the array. The elements should be assigned to the array in EC index order.
  *
- * Assuming we have n missing data locations, where n <= parity locations, the
+ * Assuming we have n missing data locations, where n {@literal <=} parity locations, the
  * ByteBuffers passed in from the client are either assigned to the decoder
  * input array, or they are assigned to the decoder output array, where
  * reconstructed data is written. The required number of parity buffers will be

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/HddsUtils.java

@@ -650,7 +650,7 @@ public static File createDir(String dirPath) {
    * Utility string formatter method to display SCM roles.
    *
    * @param nodes
-   * @return
+   * @return String
    */
   public static String format(List<String> nodes) {
     StringBuilder sb = new StringBuilder();
@@ -680,7 +680,8 @@ public static int roundupMb(long bytes) {
 
   /**
    * Unwrap exception to check if it is some kind of access control problem
-   * ({@link AccessControlException} or {@link SecretManager.InvalidToken})
+   * ({@link org.apache.hadoop.security.AccessControlException} or
+   * {@link org.apache.hadoop.security.token.SecretManager.InvalidToken})
    * or a RpcException.
    */
   public static Throwable getUnwrappedException(Exception ex) {

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/annotation/InterfaceStability.java

@@ -27,9 +27,9 @@
  * class or method not changing over time. Currently the stability can be
  * {@link Stable}, {@link Evolving} or {@link Unstable}. <br>
  *
- * <ul><li>All classes that are annotated with {@link Public} or
- * {@link LimitedPrivate} must have InterfaceStability annotation. </li>
- * <li>Classes that are {@link Private} are to be considered unstable unless
+ * <ul><li>All classes that are annotated with {@link InterfaceAudience.Public} or
+ * {@link InterfaceAudience.LimitedPrivate} must have InterfaceStability annotation. </li>
+ * <li>Classes that are {@link InterfaceAudience.Private} are to be considered unstable unless
  * a different InterfaceStability annotation states otherwise.</li>
  * <li>Incompatible changes must not be made to classes marked as stable.</li>
  * </ul>

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/client/DecommissionUtils.java

@@ -97,7 +97,7 @@ public static JsonNode getBeansJsonNode(String metricsJson) throws IOException {
    * Returns the number of decommissioning nodes.
    *
    * @param jsonNode
-   * @return
+   * @return {@code int}
    */
   public static int getNumDecomNodes(JsonNode jsonNode) {
     int numDecomNodes;
@@ -118,7 +118,7 @@ public static int getNumDecomNodes(JsonNode jsonNode) {
    * @param numDecomNodes
    * @param countsMap
    * @param errMsg
-   * @return
+   * @return {@code Map<String, Object>}
    * @throws IOException
    */
   @Nullable

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/recon/ReconConfigKeys.java

@@ -20,11 +20,12 @@
 
 /**
  * This class contains constants for Recon related configuration keys used in
- * SCM & Datanode.
+ * SCM & Datanode.
  */
 public final class ReconConfigKeys {
 
-  /**
+  /**This class contains constants for Recon related configuration keys used in
+   * SCM & Datanode.
    * Never constructed.
    */
   private ReconConfigKeys() {
@@ -71,7 +72,7 @@ private ReconConfigKeys() {
    * Recon administrator users delimited by a comma.
    * This is the list of users who can access admin only information from recon.
    * Users defined in
-   * {@link org.apache.hadoop.ozone.OzoneConfigKeys.OZONE_ADMINISTRATORS}
+   * {@link org.apache.hadoop.ozone.OzoneConfigKeys#OZONE_ADMINISTRATORS}
    * will always be able to access all recon information regardless of this
    * setting.
    */

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/ScmConfig.java

@@ -206,8 +206,7 @@ public int getScmDefaultLayoutVersionOnInit() {
    * required for SCMSecurityProtocol where the KerberosInfo references
    * the old configuration with
    * the annotation shown below:-
-   * @KerberosInfo(serverPrincipal = ScmConfigKeys
-   *    .HDDS_SCM_KERBEROS_PRINCIPAL_KEY)
+   * {@code @KerberosInfo(serverPrincipal = ScmConfigKeys.HDDS_SCM_KERBEROS_PRINCIPAL_KEY)}
    */
   public static class ConfigStrings {
     public static final String HDDS_SCM_KERBEROS_PRINCIPAL_KEY =

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/client/ScmClient.java

@@ -396,7 +396,6 @@ StartContainerBalancerResponseProto startContainerBalancer(
    * Force generates new secret keys (rotate).
    *
    * @param force boolean flag that forcefully rotates the key on demand
-   * @return
    * @throws IOException
    */
   boolean rotateSecretKeys(boolean force) throws IOException;
@@ -414,7 +413,7 @@ StartContainerBalancerResponseProto startContainerBalancer(
    * considered to be failed if it has been sent more than MAX_RETRY limit
    * and its count is reset to -1.
    *
-   * @param count Maximum num of returned transactions, if < 0. return all.
+   * @param count Maximum num of returned transactions, if {@literal < 0}. return all.
    * @param startTxId The least transaction id to start with.
    * @return a list of failed deleted block transactions.
    * @throws IOException

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/container/ReplicationManagerReport.java

@@ -146,7 +146,7 @@ public long getReportTimeStamp() {
 
   /**
    * Return a map of all stats and their value as a long.
-   * @return
+   * @return {@code Map<String, Long>}
    */
   public Map<String, Long> getStats() {
     Map<String, Long> result = new HashMap<>();
@@ -159,7 +159,7 @@ public Map<String, Long> getStats() {
   /**
    * Return a map of all samples, with the stat as the key and the samples
    * for the stat as a List of Long.
-   * @return
+   * @return {@code Map<String, List<Long>>}
    */
   public Map<String, List<Long>> getSamples() {
     Map<String, List<Long>> result = new HashMap<>();

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/ha/SCMNodeInfo.java

@@ -67,7 +67,7 @@ public class SCMNodeInfo {
   /**
    * Build SCM Node information from configuration.
    * @param conf
-   * @return
+   * @return {@code List<SCMNodeInfo>}
    */
   public static List<SCMNodeInfo> buildNodeInfo(ConfigurationSource conf) {
 

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/net/InnerNodeImpl.java

@@ -307,10 +307,13 @@ public void remove(Node node) {
    * @param loc string location of a node. If loc starts with "/", it's a
    *            absolute path, otherwise a relative path. Following examples
    *            are all accepted,
+   *            <pre>
+   *            {@code
    *            1.  /dc1/rm1/rack1          -> an inner node
    *            2.  /dc1/rm1/rack1/node1    -> a leaf node
    *            3.  rack1/node1             -> a relative path to this node
-   *
+   *            }
+   *            </pre>
    * @return null if the node is not found
    */
   @Override

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/pipeline/Pipeline.java

@@ -243,7 +243,7 @@ public int getReplicaIndex(DatanodeDetails dn) {
 
   /**
    * Get the replicaIndex Map.
-   * @return
+   * @return {@code Map<DatanodeDetails, Integer>}
    */
   public Map<DatanodeDetails, Integer> getReplicaIndexes() {
     return this.getNodes().stream().collect(Collectors.toMap(Function.identity(), this::getReplicaIndex));

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/protocol/StorageContainerLocationProtocol.java

@@ -337,7 +337,7 @@ Pipeline createReplicationPipeline(HddsProtos.ReplicationType type,
    * considered to be failed if it has been sent more than MAX_RETRY limit
    * and its count is reset to -1.
    *
-   * @param count Maximum num of returned transactions, if < 0. return all.
+   * @param count Maximum num of returned transactions, if {@literal < 0}. return all.
    * @param startTxId The least transaction id to start with.
    * @return a list of failed deleted block transactions.
    * @throws IOException

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/server/ServerUtils.java

@@ -131,7 +131,7 @@ public static InetSocketAddress updateListenAddress(OzoneConfiguration conf,
    * Fall back to OZONE_METADATA_DIRS if not defined.
    *
    * @param conf
-   * @return
+   * @return File
    */
   public static File getScmDbDir(ConfigurationSource conf) {
     File metadataDir = getDirectoryFromConfig(conf,

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/utils/LeakDetector.java

@@ -31,7 +31,6 @@
 /**
  * Simple general resource leak detector using {@link ReferenceQueue} and {@link java.lang.ref.WeakReference} to
  * observe resource object life-cycle and assert proper resource closure before they are GCed.
- *
  * <p>
  * Example usage:
  *
@@ -43,16 +42,18 @@
  *      // report leaks, don't refer to the original object (MyResource) here.
  *      System.out.println("MyResource is not closed before being discarded.");
  *   });
- *
- *   @Override
+ * }
+ * }
+ * </pre>
+ * <pre>
+ *   {@code @Override
  *   public void close() {
  *     // proper resources cleanup...
  *     // inform tracker that this object is closed properly.
  *     leakTracker.close();
  *   }
- * }
- *
- * }</pre>
+ *  }
+ * </pre>
  */
 public class LeakDetector {
   private static final Logger LOG = LoggerFactory.getLogger(LeakDetector.class);

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/utils/db/DelegatedCodec.java

@@ -23,9 +23,9 @@
 import java.io.IOException;
 
 /**
- * A {@link Codec} to serialize/deserialize objects by delegation.
+ * A {@link org.apache.hadoop.hdds.utils.db.Codec} to serialize/deserialize objects by delegation.
  *
- * @param <T>        The object type of this {@link Codec}.
+ * @param <T>        The object type of this {@link org.apache.hadoop.hdds.utils.db.Codec}.
  * @param <DELEGATE> The object type of the {@link #delegate}.
  */
 public class DelegatedCodec<T, DELEGATE> implements Codec<T> {
@@ -53,8 +53,8 @@ public enum CopyType {
    * Construct a {@link Codec} using the given delegate.
    *
    * @param delegate the delegate {@link Codec}
-   * @param forward a function to convert {@link DELEGATE} to {@link T}.
-   * @param backward a function to convert {@link T} back to {@link DELEGATE}.
+   * @param forward a function to convert {@code DELEGATE} to {@code T}.
+   * @param backward a function to convert {@code T} back to {@code DELEGATE}.
    * @param copyType How to {@link #copyObject(Object)}?
    */
   public DelegatedCodec(Codec<DELEGATE> delegate,

hadoop-hdds/common/src/main/java/org/apache/hadoop/ozone/OzoneConsts.java

@@ -363,7 +363,7 @@ private OzoneConsts() {
    * contains illegal characters when creating/renaming key.
    *
    * Avoid the following characters in a key name:
-   * "\", "{", "}", "<", ">", "^", "%", "~", "#", "|", "`", "[", "]", Quotation
+   * {@literal "\", "{", "}", "<", ">", "^", "%", "~", "#", "|", "`", "[", "]"}, Quotation
    * marks and Non-printable ASCII characters (128–255 decimal characters).
    * https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html
    */

hadoop-hdds/common/src/main/java/org/apache/hadoop/ozone/common/ChunkBuffer.java

@@ -39,13 +39,12 @@ static ChunkBuffer allocate(int capacity) {
     return allocate(capacity, 0);
   }
 
-  /**
-   * Similar to {@link ByteBuffer#allocate(int)}
+  /** Similar to {@link ByteBuffer#allocate(int)}
    * except that it can specify the increment.
    *
    * @param increment
    *   the increment size so that this buffer is allocated incrementally.
-   *   When increment <= 0, entire buffer is allocated in the beginning.
+   *   When increment {@literal <= 0}, entire buffer is allocated in the beginning.
    */
   static ChunkBuffer allocate(int capacity, int increment) {
     if (increment > 0 && increment < capacity) {