Skip to content

RATIS-2589. Fix Javadoc warnings #1505

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adoroszlai wants to merge 8 commits into
base: master
Choose a base branch
from
+14 −13
Open

RATIS-2589. Fix Javadoc warnings #1505

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
15f738f
RATIS-2589. Fix Javadoc warnings
adoroszlai Jul 2, 2026
cfa0fca
fail on javadoc warnings
adoroszlai Jul 2, 2026
dff92dc
fix checkstyle
adoroszlai Jul 2, 2026
9218560
enable release profile (for javadoc)
adoroszlai Jul 2, 2026
1247cec
do not skip javadoc in compile
adoroszlai Jul 2, 2026
7c39e80
fix javadoc for java 17
adoroszlai Jul 3, 2026
0c5d2f7
Merge remote-tracking branch 'origin/master' into RATIS-2589
adoroszlai Jul 6, 2026
43a8c3d
use «»
adoroszlai Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion dev-support/checks/compile.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
5 changes: 3 additions & 2 deletions ratis-client/src/main/java/org/apache/ratis/client/api/DataStreamInput.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion ratis-client/src/main/java/org/apache/ratis/client/api/SnapshotManagementApi.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
6 changes: 3 additions & 3 deletions ratis-common/src/main/java/org/apache/ratis/util/LifeCycle.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,13 @@
* | -------------------------------- |
* | | ------------------------ | |
* | | | | | |
* | | PAUSED <---- PAUSING---- | | |
* | | PAUSED &lt;---- PAUSING---- | | |
* | | | ^ | | | | |
* | | V | | V V V V
* NEW --> STARTING --> RUNNING --|--> CLOSING --> [CLOSED]
* NEW --&gt; STARTING --&gt; RUNNING --|--&gt; CLOSING --&gt; [CLOSED]
* ^ | | | | ^
* | | | V V |
* ------- -------> EXCEPTION -----
* ------- -------&gt; EXCEPTION -----

@szetszwo szetszwo Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use » and « . It will be easy to read the javadoc in the source.

@adoroszlai adoroszlai Jul 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the hint, it really reads better.

* </pre>
*/
public class LifeCycle {
Expand Down
2 changes: 1 addition & 1 deletion ratis-server-api/src/main/java/org/apache/ratis/server/DataStreamMap.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
2 changes: 1 addition & 1 deletion ratis-server-api/src/main/java/org/apache/ratis/server/raftlog/RaftLogSequentialOps.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
6 changes: 3 additions & 3 deletions ratis-server-api/src/main/java/org/apache/ratis/statemachine/StateMachine.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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);

Expand Down