fix: fix javadoc warnings in actor module Java sources (#3284)

He-Pin · web-flow · commit 40ad2491c176 · 2026-07-05T16:37:41.000+08:00
Motivation: Running `sbt doc` produces javadoc and compilation warnings in Java source files across actor, remote, and docs modules: multi-line {@link} tags, unresolvable Scala class references, unqualified @throws references, unchecked casts, and deprecated API usage. Modification: - ReceiveBuilder.java: Move multi-line {@link} to single line - UnitMatch.java: Replace {@link scala.PartialFunction} and {@link scala.runtime.BoxedUnit} with {@code} - UnsynchronizedByteArrayInputStream.java: Use fully qualified java.lang.IllegalArgumentException in @throws tag - Replace [[...]] with {@code} in 9 package-info.java files and other Java files - Replace {@link scala.PartialFunction} with {@code} in 11 japi/pf files - Fix multi-line {@link} tags in JavaFlowSupport.java and AsyncRecoveryPlugin.java - Add @SuppressWarnings("unchecked") to OptionalUtil.scalaNone() - Add @SuppressWarnings("deprecation") to ThrottlerTransportAdapterTest and MyJavaStateStore.deleteObject(String) - Format Java files with javafmt Result: All javadoc and compilation warnings in Java sources are eliminated. Tests: - sbt "actor / compile" (no warnings) - sbt "remote / Test / compile" (no warnings) - sbt "docs / compile" (no warnings) References: Follow-up to #3254
diff --git a/actor/src/main/java/org/apache/pekko/io/UnsynchronizedByteArrayInputStream.java b/actor/src/main/java/org/apache/pekko/io/UnsynchronizedByteArrayInputStream.java
@@ -92,7 +92,7 @@ public UnsynchronizedByteArrayInputStream(final byte[] data) {
    * @param data the buffer
    * @param offset the offset into the buffer
    * @param length the length of the buffer
-   * @throws IllegalArgumentException if the offset or length less than zero
+   * @throws java.lang.IllegalArgumentException if the offset or length less than zero
    */
   public UnsynchronizedByteArrayInputStream(final byte[] data, final int offset, final int length) {
     requireNonNegative(offset, "offset");
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/AbstractMatch.java b/actor/src/main/java/org/apache/pekko/japi/pf/AbstractMatch.java
@@ -16,7 +16,7 @@
 import scala.PartialFunction;
 
 /**
- * Version of {@link scala.PartialFunction} that can be built during runtime from Java.
+ * Version of {@code scala.PartialFunction} that can be built during runtime from Java.
  *
  * @param <I> the input type, that this PartialFunction will be applied to
  * @param <R> the return type, that the results of the application will have
@@ -32,7 +32,7 @@ class AbstractMatch<I, R> {
   }
 
   /**
-   * Turn this {@link Match} into a {@link scala.PartialFunction}.
+   * Turn this {@link Match} into a {@code scala.PartialFunction}.
    *
    * @return a partial function representation ot his {@link Match}
    */
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/AbstractPFBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/AbstractPFBuilder.java
@@ -16,7 +16,7 @@
 import scala.PartialFunction;
 
 /**
- * A builder for {@link scala.PartialFunction}.
+ * A builder for {@code scala.PartialFunction}.
  *
  * @param <F> the input type, that this PartialFunction will be applied to
  * @param <T> the return type, that the results of the application will have
@@ -31,7 +31,7 @@ protected void addStatement(PartialFunction<F, T> statement) {
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/FSMStateFunctionBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/FSMStateFunctionBuilder.java
@@ -263,7 +263,7 @@ public FSMStateFunctionBuilder<S, D> anyEvent(final Function2<Object, D, FSM.Sta
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/FSMStopBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/FSMStopBuilder.java
@@ -122,7 +122,7 @@ public void apply(FSM.StopEvent e) throws Exception {
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/FSMTransitionHandlerBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/FSMTransitionHandlerBuilder.java
@@ -91,7 +91,7 @@ public void apply(Tuple2 t) throws Exception {
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/Match.java b/actor/src/main/java/org/apache/pekko/japi/pf/Match.java
@@ -19,7 +19,7 @@
 import scala.PartialFunction;
 
 /**
- * Version of {@link scala.PartialFunction} that can be built during runtime from Java.
+ * Version of {@code scala.PartialFunction} that can be built during runtime from Java.
  *
  * @param <I> the input type, that this PartialFunction will be applied to
  * @param <R> the return type, that the results of the application will have
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/PFBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/PFBuilder.java
@@ -17,7 +17,7 @@
 import org.apache.pekko.japi.function.Predicate;
 
 /**
- * A builder for {@link scala.PartialFunction}.
+ * A builder for {@code scala.PartialFunction}.
  *
  * @param <I> the input type, that this PartialFunction will be applied to
  * @param <R> the return type, that the results of the application will have
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/ReceiveBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/ReceiveBuilder.java
@@ -57,7 +57,7 @@ protected void addStatement(PartialFunction<Object, BoxedUnit> statement) {
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/UnitMatch.java b/actor/src/main/java/org/apache/pekko/japi/pf/UnitMatch.java
@@ -20,8 +20,8 @@
 import scala.runtime.BoxedUnit;
 
 /**
- * Version of {@link scala.PartialFunction} that can be built during runtime from Java. This is a
- * specialized version of {@link UnitMatch} to map java void methods to {@link
+ * Version of {@code scala.PartialFunction} that can be built during runtime from Java. This is a
+ * specialized version of {@link UnitMatch} to map java void methods to {@code
  * scala.runtime.BoxedUnit}.
  *
  * @param <I> the input type, that this PartialFunction will be applied to
diff --git a/actor/src/main/java/org/apache/pekko/japi/pf/UnitPFBuilder.java b/actor/src/main/java/org/apache/pekko/japi/pf/UnitPFBuilder.java
@@ -18,8 +18,8 @@
 import scala.runtime.BoxedUnit;
 
 /**
- * A builder for {@link scala.PartialFunction}. This is a specialized version of {@link PFBuilder}
- * to map java void methods to {@link scala.runtime.BoxedUnit}.
+ * A builder for {@code scala.PartialFunction}. This is a specialized version of {@link PFBuilder}
+ * to map java void methods to {@code scala.runtime.BoxedUnit}.
  *
  * @param <I> the input type, that this PartialFunction to be applied to
  */
diff --git a/persistence-query/src/main/java/org/apache/pekko/persistence/query/javadsl/package-info.java b/persistence-query/src/main/java/org/apache/pekko/persistence/query/javadsl/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Persistence Query.
  *
- * <p>This package contains the Java DSL for Pekko Persistence Query. For the Scala DSL see
- * [[org.apache.pekko.persistence.query.scaladsl]].
+ * <p>This package contains the Java DSL for Pekko Persistence Query. For the Scala DSL see {@code
+ * org.apache.pekko.persistence.query.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.persistence.query.javadsl;
diff --git a/persistence-testkit/src/main/java/org/apache/pekko/persistence/testkit/javadsl/package-info.java b/persistence-testkit/src/main/java/org/apache/pekko/persistence/testkit/javadsl/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Persistence TestKit.
  *
- * <p>This package contains the Java DSL for Pekko Persistence TestKit. For the Scala DSL see
- * [[org.apache.pekko.persistence.testkit.scaladsl]].
+ * <p>This package contains the Java DSL for Pekko Persistence TestKit. For the Scala DSL see {@code
+ * org.apache.pekko.persistence.testkit.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.persistence.testkit.javadsl;
diff --git a/persistence-typed/src/main/java/org/apache/pekko/persistence/typed/javadsl/package-info.java b/persistence-typed/src/main/java/org/apache/pekko/persistence/typed/javadsl/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Persistence Typed.
  *
- * <p>This package contains the Java DSL for Pekko Persistence Typed. For the Scala DSL see
- * [[org.apache.pekko.persistence.typed.scaladsl]].
+ * <p>This package contains the Java DSL for Pekko Persistence Typed. For the Scala DSL see {@code
+ * org.apache.pekko.persistence.typed.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.persistence.typed.javadsl;
diff --git a/persistence/src/main/java/org/apache/pekko/persistence/fsm/japi/pf/FSMStateFunctionBuilder.java b/persistence/src/main/java/org/apache/pekko/persistence/fsm/japi/pf/FSMStateFunctionBuilder.java
@@ -287,7 +287,7 @@ public FSMStateFunctionBuilder<S, D, E> anyEvent(
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/persistence/src/main/java/org/apache/pekko/persistence/fsm/japi/pf/FSMStopBuilder.java b/persistence/src/main/java/org/apache/pekko/persistence/fsm/japi/pf/FSMStopBuilder.java
@@ -133,7 +133,7 @@ public void apply(org.apache.pekko.persistence.fsm.PersistentFSM.StopEvent e)
   }
 
   /**
-   * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be
+   * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be
    * reset.
    *
    * @return a PartialFunction for this builder.
diff --git a/persistence/src/main/java/org/apache/pekko/persistence/journal/japi/AsyncRecoveryPlugin.java b/persistence/src/main/java/org/apache/pekko/persistence/journal/japi/AsyncRecoveryPlugin.java
@@ -51,8 +51,8 @@ CompletionStage<Void> doAsyncReplayMessages(
    * Java API, Plugin API: asynchronously reads the highest stored sequence number for the given
    * `persistenceId`. The persistent actor will use the highest sequence number after recovery as
    * the starting point when persisting new events. This sequence number is also used as
-   * `toSequenceNr` in subsequent call to [[#asyncReplayMessages]] unless the user has specified a
-   * lower `toSequenceNr`.
+   * `toSequenceNr` in subsequent call to {@code #asyncReplayMessages} unless the user has specified
+   * a lower `toSequenceNr`.
    *
    * @param persistenceId id of the persistent actor.
    * @param fromSequenceNr hint where to start searching for the highest sequence number.
diff --git a/persistence/src/main/java/org/apache/pekko/persistence/journal/japi/package-info.java b/persistence/src/main/java/org/apache/pekko/persistence/journal/japi/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Persistence Journal.
  *
- * <p>This package contains the Java DSL for Pekko Persistence Journal. For the Scala DSL see
- * [[org.apache.pekko.persistence.journal]].
+ * <p>This package contains the Java DSL for Pekko Persistence Journal. For the Scala DSL see {@code
+ * org.apache.pekko.persistence.journal}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.persistence.journal.japi;
diff --git a/persistence/src/main/java/org/apache/pekko/persistence/snapshot/japi/package-info.java b/persistence/src/main/java/org/apache/pekko/persistence/snapshot/japi/package-info.java
@@ -19,7 +19,7 @@
  * Java API for Pekko Persistence Snapshot Store.
  *
  * <p>This package contains the Java DSL for Pekko Persistence Snapshot Store. For the Scala DSL see
- * [[org.apache.pekko.persistence.snapshot]].
+ * {@code org.apache.pekko.persistence.snapshot}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.persistence.snapshot.japi;
diff --git a/persistence/src/main/java/org/apache/pekko/persistence/state/javadsl/package-info.java b/persistence/src/main/java/org/apache/pekko/persistence/state/javadsl/package-info.java
@@ -19,7 +19,7 @@
  * Java API for Pekko Persistence Durable State.
  *
  * <p>This package contains the Java DSL for Pekko Persistence Durable State. For the Scala DSL see
- * [[org.apache.pekko.persistence.state.scaladsl]].
+ * {@code org.apache.pekko.persistence.state.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.persistence.state.javadsl;
diff --git a/stream-testkit/src/main/java/org/apache/pekko/stream/testkit/javadsl/package-info.java b/stream-testkit/src/main/java/org/apache/pekko/stream/testkit/javadsl/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Streams TestKit.
  *
- * <p>This package contains the Java DSL for Pekko Streams TestKit. For the Scala DSL see
- * [[org.apache.pekko.stream.testkit.scaladsl]].
+ * <p>This package contains the Java DSL for Pekko Streams TestKit. For the Scala DSL see {@code
+ * org.apache.pekko.stream.testkit.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.stream.testkit.javadsl;
diff --git a/stream-typed/src/main/java/org/apache/pekko/stream/typed/javadsl/package-info.java b/stream-typed/src/main/java/org/apache/pekko/stream/typed/javadsl/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Streams Typed.
  *
- * <p>This package contains the Java DSL for Pekko Streams Typed. For the Scala DSL see
- * [[org.apache.pekko.stream.typed.scaladsl]].
+ * <p>This package contains the Java DSL for Pekko Streams Typed. For the Scala DSL see {@code
+ * org.apache.pekko.stream.typed.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.stream.typed.javadsl;
diff --git a/stream/src/main/java/org/apache/pekko/stream/javadsl/FramingTruncation.java b/stream/src/main/java/org/apache/pekko/stream/javadsl/FramingTruncation.java
@@ -13,7 +13,7 @@
 
 package org.apache.pekko.stream.javadsl;
 
-/** Determines mode in which [[Framing]] operates. */
+/** Determines mode in which {@code Framing} operates. */
 public enum FramingTruncation {
   ALLOW,
   DISALLOW
diff --git a/stream/src/main/java/org/apache/pekko/stream/javadsl/JavaFlowSupport.java b/stream/src/main/java/org/apache/pekko/stream/javadsl/JavaFlowSupport.java
@@ -32,7 +32,8 @@ private JavaFlowSupport() {
   }
 
   /**
-   * {@link org.apache.pekko.stream.javadsl.Flow]] factories operating with {@code java.util.concurrent.Flow.*} interfaces.
+   * {@link org.apache.pekko.stream.javadsl.Flow} factories operating with {@code
+   * java.util.concurrent.Flow.*} interfaces.
    */
   public static final class Source {
     private Source() {
@@ -75,7 +76,8 @@ public static <T> org.apache.pekko.stream.javadsl.Source<T, NotUsed> fromPublish
   }
 
   /**
-   * {@link org.apache.pekko.stream.javadsl.Flow]] factories operating with {@code java.util.concurrent.Flow.*} interfaces.
+   * {@link org.apache.pekko.stream.javadsl.Flow} factories operating with {@code
+   * java.util.concurrent.Flow.*} interfaces.
    */
   public static final class Flow {
     private Flow() {
@@ -89,7 +91,8 @@ public static <I, O> org.apache.pekko.stream.javadsl.Flow<I, O, NotUsed> fromPro
     }
 
     /**
-     * Creates a Flow from a {@link java.util.concurrent.Flow.Processor>> and returns a materialized value.
+     * Creates a Flow from a {@link java.util.concurrent.Flow.Processor} and returns a materialized
+     * value.
      */
     public static <I, O, M> org.apache.pekko.stream.javadsl.Flow<I, O, M> fromProcessorMat(
         org.apache.pekko.japi.function.Creator<
diff --git a/stream/src/main/java/org/apache/pekko/stream/javadsl/package-info.java b/stream/src/main/java/org/apache/pekko/stream/javadsl/package-info.java
@@ -18,8 +18,8 @@
 /**
  * Java API for Pekko Streams.
  *
- * <p>This package contains the Java DSL for Pekko Streams. For the Scala DSL see
- * [[org.apache.pekko.stream.scaladsl]].
+ * <p>This package contains the Java DSL for Pekko Streams. For the Scala DSL see {@code
+ * org.apache.pekko.stream.scaladsl}.
  */
 @org.jspecify.annotations.NullMarked
 package org.apache.pekko.stream.javadsl;

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@`
`16`	`16`	`import scala.PartialFunction;`
`17`	`17`
`18`	`18`	`/**`
`19`		`- * Version of {@link scala.PartialFunction} that can be built during runtime from Java.`
	`19`	`+ * Version of {@code scala.PartialFunction} that can be built during runtime from Java.`
`20`	`20`	`*`
`21`	`21`	`* @param <I> the input type, that this PartialFunction will be applied to`
`22`	`22`	`* @param <R> the return type, that the results of the application will have`
`@@ -32,7 +32,7 @@ class AbstractMatch<I, R> {`
`32`	`32`	`}`
`33`	`33`
`34`	`34`	`/**`
`35`		`- * Turn this {@link Match} into a {@link scala.PartialFunction}.`
	`35`	`+ * Turn this {@link Match} into a {@code scala.PartialFunction}.`
`36`	`36`	`*`
`37`	`37`	`* @return a partial function representation ot his {@link Match}`
`38`	`38`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -263,7 +263,7 @@ public FSMStateFunctionBuilder<S, D> anyEvent(final Function2<Object, D, FSM.Sta`
`263`	`263`	`}`
`264`	`264`
`265`	`265`	`/**`
`266`		`- * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be`
	`266`	`+ * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be`
`267`	`267`	`* reset.`
`268`	`268`	`*`
`269`	`269`	`* @return a PartialFunction for this builder.`
Original file line number	Diff line number	Diff line change
`@@ -122,7 +122,7 @@ public void apply(FSM.StopEvent e) throws Exception {`
`122`	`122`	`}`
`123`	`123`
`124`	`124`	`/**`
`125`		`- * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be`
	`125`	`+ * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be`
`126`	`126`	`* reset.`
`127`	`127`	`*`
`128`	`128`	`* @return a PartialFunction for this builder.`
Original file line number	Diff line number	Diff line change
`@@ -91,7 +91,7 @@ public void apply(Tuple2 t) throws Exception {`
`91`	`91`	`}`
`92`	`92`
`93`	`93`	`/**`
`94`		`- * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be`
	`94`	`+ * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be`
`95`	`95`	`* reset.`
`96`	`96`	`*`
`97`	`97`	`* @return a PartialFunction for this builder.`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@`
`19`	`19`	`import scala.PartialFunction;`
`20`	`20`
`21`	`21`	`/**`
`22`		`- * Version of {@link scala.PartialFunction} that can be built during runtime from Java.`
	`22`	`+ * Version of {@code scala.PartialFunction} that can be built during runtime from Java.`
`23`	`23`	`*`
`24`	`24`	`* @param <I> the input type, that this PartialFunction will be applied to`
`25`	`25`	`* @param <R> the return type, that the results of the application will have`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@`
`17`	`17`	`import org.apache.pekko.japi.function.Predicate;`
`18`	`18`
`19`	`19`	`/**`
`20`		`- * A builder for {@link scala.PartialFunction}.`
	`20`	`+ * A builder for {@code scala.PartialFunction}.`
`21`	`21`	`*`
`22`	`22`	`* @param <I> the input type, that this PartialFunction will be applied to`
`23`	`23`	`* @param <R> the return type, that the results of the application will have`
Original file line number	Diff line number	Diff line change
`@@ -57,7 +57,7 @@ protected void addStatement(PartialFunction<Object, BoxedUnit> statement) {`
`57`	`57`	`}`
`58`	`58`
`59`	`59`	`/**`
`60`		`- * Build a {@link scala.PartialFunction} from this builder. After this call the builder will be`
	`60`	`+ * Build a {@code scala.PartialFunction} from this builder. After this call the builder will be`
`61`	`61`	`* reset.`
`62`	`62`	`*`
`63`	`63`	`* @return a PartialFunction for this builder.`