RATIS-2589. Fix Javadoc warnings (#1505)

Author: adoroszlai

.github/workflows/ci.yaml

@@ -55,7 +55,7 @@ jobs:
       java-version: ${{ matrix.java }}
       needs-source-tarball: true
       script: compile
-      script-args: -Dmaven.compiler.release=${{ matrix.java }}
+      script-args: -Prelease -Dmaven.compiler.release=${{ matrix.java }} -Dmaven.javadoc.failOnWarnings=${{ matrix.java != 8 }}
       split: ${{ matrix.java }}
       timeout-minutes: 30
     secrets:

dev-support/checks/compile.sh

@@ -20,7 +20,7 @@ source "${DIR}/../find_maven.sh"
 
 : ${WITH_COVERAGE:="false"}
 
-MAVEN_OPTIONS='-V -B -Dmaven.javadoc.skip=true -DskipTests'
+MAVEN_OPTIONS='-V -B -DskipTests'
 
 if [[ "${WITH_COVERAGE}" != "true" ]]; then
   MAVEN_OPTIONS="${MAVEN_OPTIONS} -Djacoco.skip"

ratis-client/src/main/java/org/apache/ratis/client/api/DataStreamInput.java

@@ -30,8 +30,9 @@ public interface DataStreamInput extends Closeable {
   /**
    * Read the next chunk in the stream asynchronously.
    * The caller owns the returned {@link DataStreamReply} which is a {@link ReferenceCountedObject}.
-   * and a {@link DataStreamPacket}. Access the buffer via {@link DataStreamPacket#nioBuffer()}
-   * or {@link DataStreamPacket#nioBuffers()}.
+   * and a {@link org.apache.ratis.protocol.DataStreamPacket}.
+   * Access the buffer via {@link org.apache.ratis.protocol.DataStreamPacket#nioBuffer()}
+   * or {@link org.apache.ratis.protocol.DataStreamPacket#nioBuffers()}.
    * It must call {@link ReferenceCountedObject#release()} after consuming it.
    *
    * @return a future of the reference-counted reply.

ratis-client/src/main/java/org/apache/ratis/client/api/SnapshotManagementApi.java

@@ -40,7 +40,7 @@ default RaftClientReply create(boolean force, long timeoutMs) throws IOException
     /**
    * Trigger to create a snapshot.
    *
-   * @param creationGap When (creationGap > 0) and (lastAppliedIndex - lastSnapshotIndex < creationGap),
+   * @param creationGap When (creationGap &gt; 0) and (lastAppliedIndex - lastSnapshotIndex &lt; creationGap),
    *                    return lastSnapshotIndex; otherwise, take a new snapshot and then return its index.
    *                    When creationGap == 0, use the server configured value as the creationGap.
    * @return a reply.  When {@link RaftClientReply#isSuccess()} is true,

ratis-common/src/main/java/org/apache/ratis/util/LifeCycle.java

@@ -40,13 +40,13 @@
  *  |        --------------------------------         |
  *  |       |     ------------------------   |        |
  *  |       |    |                        |  |        |
- *  |       |  PAUSED <---- PAUSING----   |  |        |
+ *  |       |  PAUSED «---- PAUSING----   |  |        |
  *  |       |    |          ^     |    |  |  |        |
  *  |       |    V          |     |    V  V  V        V
- * NEW --> STARTING --> RUNNING --|--> CLOSING --> [CLOSED]
+ * NEW --» STARTING --» RUNNING --|--» CLOSING --» [CLOSED]
  *  ^       |    |          |     |       ^
  *  |       |    |          V     V       |
- *   -------      -------> EXCEPTION -----
+ *   -------      -------» EXCEPTION -----
  * </pre>
  */
 public class LifeCycle {

ratis-server-api/src/main/java/org/apache/ratis/server/DataStreamMap.java

@@ -29,6 +29,6 @@ public interface DataStreamMap {
   CompletableFuture<DataStream> computeIfAbsent(ClientInvocationId invocationId,
       Function<ClientInvocationId, CompletableFuture<DataStream>> newDataStream);
 
-  /** Similar to {@link java.util.Map#remove(java.lang.Object). */
+  /** Similar to {@link java.util.Map#remove(java.lang.Object)}. */
   CompletableFuture<DataStream> remove(ClientInvocationId invocationId);
 }

ratis-server-api/src/main/java/org/apache/ratis/server/raftlog/RaftLogSequentialOps.java

@@ -134,7 +134,7 @@ default CompletableFuture<Long> appendEntry(LogEntryProto entry, TransactionCont
   /**
    * The same as append(Arrays.asList(entries)).
    *
-   * @deprecated use {@link #append(List)}
+   * @deprecated use {@link RaftLogSequentialOps#append(List)}
    */
   @Deprecated
   default List<CompletableFuture<Long>> append(LogEntryProto... entries) {

ratis-server-api/src/main/java/org/apache/ratis/statemachine/StateMachine.java

@@ -226,7 +226,7 @@ default void notifySnapshotInstalled(InstallSnapshotResult result, long snapshot
 
     /**
      * Notify the {@link StateMachine} that the server for this division has been shut down.
-     * @Deprecated please use/override {@link #notifyServerShutdown(RoleInfoProto, boolean)} instead
+     * @deprecated please use/override {@link #notifyServerShutdown(RoleInfoProto, boolean)} instead
      */
     @Deprecated
     default void notifyServerShutdown(RoleInfoProto roleInfo) {
@@ -503,15 +503,15 @@ default FollowerEventApi followerEvent() {
   CompletableFuture<Message> query(Message request);
 
   /**
-   * Query the state machine, provided minIndex <= commit index.
+   * Query the state machine, provided minIndex &lt;= commit index.
    * The request must be read-only.
    * Since the commit index of this server may lag behind the Raft service,
    * the returned result may possibly be stale.
    *
    * When minIndex > {@link #getLastAppliedTermIndex()},
    * the state machine may choose to either
    * (1) return exceptionally, or
-   * (2) wait until minIndex <= {@link #getLastAppliedTermIndex()} before running the query.
+   * (2) wait until minIndex &lt;= {@link #getLastAppliedTermIndex()} before running the query.
    */
   CompletableFuture<Message> queryStale(Message request, long minIndex);