= #17380 fix doc comments for java8 doclint

* actor and cluster-metrics comments
* agent/camel/cluster/osgi/persistence/remote comments
* comments in contrib/persistence-tck/multi-node/typed

akka-actor-tests/src/test/scala/akka/pattern/AskSpec.scala

@@ -12,6 +12,8 @@ import scala.concurrent.Await
 import scala.concurrent.duration._
 import scala.util.Failure
 
+import language.postfixOps
+
 class AskSpec extends AkkaSpec with ScalaFutures {
 
   "The “ask” pattern" must {

akka-actor/src/main/scala/akka/AkkaException.scala

@@ -5,11 +5,7 @@
 package akka
 
 /**
- * Akka base Exception. Each Exception gets:
- * <ul>
- *   <li>a uuid for tracking purposes</li>
- *   <li>toString that includes exception name, message and uuid</li>
- * </ul>
+ * Akka base Exception.
  */
 @SerialVersionUID(1L)
 class AkkaException(message: String, cause: Throwable) extends RuntimeException(message, cause) with Serializable {

akka-actor/src/main/scala/akka/actor/AbstractActor.scala

@@ -109,7 +109,7 @@ abstract class AbstractLoggingActor extends AbstractActor with ActorLogging
  * }
  * </pre>
  * Note that the subclasses of `AbstractActorWithStash` by default request a Deque based mailbox since this class
- * implements the `RequiresMessageQueue<DequeBasedMessageQueueSemantics>` marker interface.
+ * implements the `RequiresMessageQueue&lt;DequeBasedMessageQueueSemantics&gt;` marker interface.
  * You can override the default mailbox provided when `DequeBasedMessageQueueSemantics` are requested via config:
  * <pre>
  *   akka.actor.mailbox.requirements {

akka-actor/src/main/scala/akka/actor/ActorPath.scala

@@ -27,15 +27,15 @@ object ActorPath {
 
   /**
    * Validates the given actor path element and throws an [[InvalidActorNameException]] if invalid.
-   * See [[isValidPathElement()]] for a non-throwing version.
+   * See [[#isValidPathElement]] for a non-throwing version.
    *
    * @param element actor path element to be validated
    */
   final def validatePathElement(element: String): Unit = validatePathElement(element, fullPath = null)
 
   /**
    * Validates the given actor path element and throws an [[InvalidActorNameException]] if invalid.
-   * See [[isValidPathElement()]] for a non-throwing version.
+   * See [[#isValidPathElement]] for a non-throwing version.
    *
    * @param element actor path element to be validated
    * @param fullPath optional fullPath element that may be included for better error messages; null if not given
@@ -60,7 +60,7 @@ object ActorPath {
   /**
    * This method is used to validate a path element (Actor Name).
    * Since Actors form a tree, it is addressable using an URL, therefore an Actor Name has to conform to:
-   * [[http://www.ietf.org/rfc/rfc2396.txt RFC-2396]].
+   * <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC-2396</a>.
    *
    * User defined Actor names may not start from a `$` sign - these are reserved for system names.
    */
@@ -97,7 +97,7 @@ object ActorPath {
  * ActorPath defines a natural ordering (so that ActorRefs can be put into
  * collections with this requirement); this ordering is intended to be as fast
  * as possible, which owing to the bottom-up recursive nature of ActorPath
- * is sorted by path elements FROM RIGHT TO LEFT, where RootActorPath >
+ * is sorted by path elements FROM RIGHT TO LEFT, where RootActorPath &gt;
  * ChildActorPath in case the number of elements is different.
  *
  * Two actor paths are compared equal when they have the same name and parent

akka-actor/src/main/scala/akka/actor/ActorRef.scala

@@ -118,7 +118,7 @@ abstract class ActorRef extends java.lang.Comparable[ActorRef] with Serializable
    * Sends the specified message to this ActorRef, i.e. fire-and-forget
    * semantics, including the sender reference if possible.
    *
-   * Pass [[akka.actor.ActorRef$.noSender]] or `null` as sender if there is nobody to reply to
+   * Pass [[akka.actor.ActorRef]] `noSender` or `null` as sender if there is nobody to reply to
    */
   final def tell(msg: Any, sender: ActorRef): Unit = this.!(msg)(sender)
 
@@ -157,7 +157,7 @@ abstract class ActorRef extends java.lang.Comparable[ActorRef] with Serializable
 /**
  * This trait represents the Scala Actor API
  * There are implicit conversions in ../actor/Implicits.scala
- * from ActorRef -> ScalaActorRef and back
+ * from ActorRef -> ScalaActorRef and back
  */
 trait ScalaActorRef { ref: ActorRef ⇒
 

akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala

@@ -358,9 +358,9 @@ private[akka] object SystemGuardian {
   /**
    * For the purpose of orderly shutdown it's possible
    * to register interest in the termination of systemGuardian
-   * and receive a notification [[akka.actor.Guardian.TerminationHook]]
+   * and receive a notification `TerminationHook`
    * before systemGuardian is stopped. The registered hook is supposed
-   * to reply with [[akka.actor.Guardian.TerminationHookDone]] and the
+   * to reply with `TerminationHookDone` and the
    * systemGuardian will not stop until all registered hooks have replied.
    */
   case object RegisterTerminationHook

akka-actor/src/main/scala/akka/actor/ActorSelection.scala

@@ -101,7 +101,7 @@ abstract class ActorSelection extends Serializable {
 
   /**
    * String representation of the actor selection suitable for storage and recreation.
-   * The output is similar to the URI fragment returned by [[akka.actor.ActorPath.toSerializationFormat]].
+   * The output is similar to the URI fragment returned by [[akka.actor.ActorPath#toSerializationFormat]].
    * @return URI fragment
    */
   def toSerializationFormat: String = {

akka-actor/src/main/scala/akka/actor/ActorSystem.scala

@@ -291,7 +291,7 @@ abstract class ActorSystem extends ActorRefFactory {
   def logConfiguration(): Unit
 
   /**
-   * Construct a path below the application guardian to be used with [[ActorSystem.actorSelection]].
+   * Construct a path below the application guardian to be used with [[ActorSystem#actorSelection]].
    */
   def /(name: String): ActorPath
 
@@ -301,7 +301,7 @@ abstract class ActorSystem extends ActorRefFactory {
   def child(child: String): ActorPath = /(child)
 
   /**
-   * Construct a path below the application guardian to be used with [[ActorSystem.actorSelection]].
+   * Construct a path below the application guardian to be used with [[ActorSystem#actorSelection]].
    */
   def /(name: Iterable[String]): ActorPath
 
@@ -326,7 +326,7 @@ abstract class ActorSystem extends ActorRefFactory {
   def eventStream: EventStream
 
   /**
-   * Convenient logging adapter for logging to the [[ActorSystem.eventStream]].
+   * Convenient logging adapter for logging to the [[ActorSystem#eventStream]].
    */
   def log: LoggingAdapter
 
@@ -369,7 +369,7 @@ abstract class ActorSystem extends ActorRefFactory {
    * The callbacks will be run sequentially in reverse order of registration, i.e.
    * last registration is run first.
    *
-   * @throws a RejectedExecutionException if the System has already shut down or if shutdown has been initiated.
+   * Throws a RejectedExecutionException if the System has already shut down or if shutdown has been initiated.
    *
    * Scala API
    */
@@ -382,7 +382,7 @@ abstract class ActorSystem extends ActorRefFactory {
    * The callbacks will be run sequentially in reverse order of registration, i.e.
    * last registration is run first.
    *
-   * @throws a RejectedExecutionException if the System has already shut down or if shutdown has been initiated.
+   * Throws a RejectedExecutionException if the System has already shut down or if shutdown has been initiated.
    */
   def registerOnTermination(code: Runnable): Unit
 
@@ -391,7 +391,7 @@ abstract class ActorSystem extends ActorRefFactory {
    * timeout has elapsed. This will block until after all on termination
    * callbacks have been run.
    *
-   * @throws TimeoutException in case of timeout
+   * Throws TimeoutException in case of timeout.
    */
   @deprecated("Use Await.result(whenTerminated, timeout) instead", "2.4")
   def awaitTermination(timeout: Duration): Unit
@@ -407,7 +407,7 @@ abstract class ActorSystem extends ActorRefFactory {
    * Stop this actor system. This will stop the guardian actor, which in turn
    * will recursively stop all its child actors, then the system guardian
    * (below which the logging actors reside) and the execute all registered
-   * termination handlers (see [[ActorSystem.registerOnTermination]]).
+   * termination handlers (see [[ActorSystem#registerOnTermination]]).
    */
   @deprecated("Use the terminate() method instead", "2.4")
   def shutdown(): Unit
@@ -426,7 +426,7 @@ abstract class ActorSystem extends ActorRefFactory {
    * Terminates this actor system. This will stop the guardian actor, which in turn
    * will recursively stop all its child actors, then the system guardian
    * (below which the logging actors reside) and the execute all registered
-   * termination handlers (see [[ActorSystem.registerOnTermination]]).
+   * termination handlers (see [[ActorSystem#registerOnTermination]]).
    */
   def terminate(): Future[Terminated]
 
@@ -835,7 +835,7 @@ private[akka] class ActorSystemImpl(
      * Adds a Runnable that will be executed on ActorSystem termination.
      * Note that callbacks are executed in reverse order of insertion.
      * @param r The callback to be executed on ActorSystem termination
-     * @throws RejectedExecutionException if called after ActorSystem has been terminated
+     * Throws RejectedExecutionException if called after ActorSystem has been terminated.
      */
     final def add(r: Runnable): Unit = {
       @tailrec def addRec(r: Runnable, p: Promise[T]): Unit = ref.get match {

akka-actor/src/main/scala/akka/actor/Address.scala

@@ -46,7 +46,7 @@ final case class Address private (protocol: String, system: String, host: Option
   /**
    * Returns the canonical String representation of this Address formatted as:
    *
-   * <protocol>://<system>@<host>:<port>
+   * `protocol://system@host:port`
    */
   @transient
   override lazy val toString: String = {
@@ -61,7 +61,7 @@ final case class Address private (protocol: String, system: String, host: Option
   /**
    * Returns a String representation formatted as:
    *
-   * <system>@<host>:<port>
+   * `system@host:port`
    */
   def hostPort: String = toString.substring(protocol.length + 3)
 }

akka-actor/src/main/scala/akka/actor/Deployer.scala

@@ -60,7 +60,7 @@ final case class Deploy(
   /**
    * Do a merge between this and the other Deploy, where values from “this” take
    * precedence. The “path” of the other Deploy is not taken into account. All
-   * other members are merged using ``<X>.withFallback(other.<X>)``.
+   * other members are merged using `X.withFallback(other.X)`.
    */
   def withFallback(other: Deploy): Deploy = {
     Deploy(

akka-actor/src/main/scala/akka/actor/FSM.scala

@@ -70,7 +70,7 @@ object FSM {
   /**
    * Signifies that the [[akka.actor.FSM]] is shutting itself down because of
    * an error, e.g. if the state to transition into does not exist. You can use
-   * this to communicate a more precise cause to the [[akka.actor.FSM.onTermination]] block.
+   * this to communicate a more precise cause to the `onTermination` block.
    */
   final case class Failure(cause: Any) extends Reason
 
@@ -374,7 +374,7 @@ trait FSM[S, D] extends Actor with Listeners with ActorLogging {
    * Return this from a state function when no state change is to be effected.
    *
    * No transition event will be triggered by [[#stay]].
-   * If you want to trigger an event like `S -> S` for [[#onTransition]] to handle use [[#goto]] instead.
+   * If you want to trigger an event like `S -> S` for `onTransition` to handle use `goto` instead.
    *
    * @return descriptor for staying in current state
    */
@@ -410,7 +410,6 @@ trait FSM[S, D] extends Actor with Listeners with ActorLogging {
    * @param msg message to be delivered
    * @param timeout delay of first message delivery and between subsequent messages
    * @param repeat send once if false, scheduleAtFixedRate if true
-   * @return current state descriptor
    */
   final def setTimer(name: String, msg: Any, timeout: FiniteDuration, repeat: Boolean = false): Unit = {
     if (debugEvent)
@@ -1160,7 +1159,6 @@ abstract class AbstractFSM[S, D] extends FSM[S, D] {
    * @param name identifier to be used with cancelTimer()
    * @param msg message to be delivered
    * @param timeout delay of first message delivery and between subsequent messages
-   * @return current state descriptor
    */
   final def setTimer(name: String, msg: Any, timeout: FiniteDuration): Unit =
     setTimer(name, msg, timeout, false)

akka-actor/src/main/scala/akka/actor/FaultHandling.scala

@@ -145,7 +145,7 @@ object SupervisorStrategy extends SupervisorStrategyLowPriorityImplicits {
 
   /**
    * When supervisorStrategy is not specified for an actor this
-   * [[Decider]] is used by default in the supervisor strategy.
+   * `Decider` is used by default in the supervisor strategy.
    * The child will be stopped when [[akka.actor.ActorInitializationException]],
    * [[akka.actor.ActorKilledException]], or [[akka.actor.DeathPactException]] is
    * thrown. It will be restarted for other `Exception` types.

akka-actor/src/main/scala/akka/actor/Scheduler.scala

@@ -187,7 +187,7 @@ trait Cancellable {
  * when scheduling single-shot tasks, instead it always rounds up the task
  * delay to a full multiple of the TickDuration. This means that tasks are
  * scheduled possibly one tick later than they could be (if checking that
- * “now() + delay <= nextTick” were done).
+ * “now() + delay &lt;= nextTick” were done).
  */
 class LightArrayRevolverScheduler(config: Config,
                                   log: LoggingAdapter,

akka-actor/src/main/scala/akka/actor/TypedActor.scala

@@ -138,7 +138,7 @@ object TypedActor extends ExtensionId[TypedActorExtension] with ExtensionIdProvi
     /**
      * Invokes the Method on the supplied instance
      *
-     * @throws the underlying exception if there's an InvocationTargetException thrown on the invocation
+     * Throws the underlying exception if there's an InvocationTargetException thrown on the invocation.
      */
     def apply(instance: AnyRef): AnyRef = try {
       parameters match {
@@ -217,8 +217,9 @@ object TypedActor extends ExtensionId[TypedActorExtension] with ExtensionIdProvi
    *
    * NEVER EXPOSE "this" to someone else, always use "self[TypeOfInterface(s)]"
    *
-   * @throws IllegalStateException if called outside of the scope of a method on this TypedActor
-   * @throws ClassCastException if the supplied type T isn't the type of the proxy associated with this TypedActor
+   * Throws IllegalStateException if called outside of the scope of a method on this TypedActor.
+   *
+   * Throws ClassCastException if the supplied type T isn't the type of the proxy associated with this TypedActor.
    */
   def self[T <: AnyRef] = selfReference.get.asInstanceOf[T] match {
     case null ⇒ throw new IllegalStateException("Calling TypedActor.self outside of a TypedActor implementation method!")

akka-actor/src/main/scala/akka/actor/UntypedActorWithStash.scala

@@ -30,7 +30,7 @@ package akka.actor
  *   }
  * </pre>
  * Note that the subclasses of `UntypedActorWithStash` by default request a Deque based mailbox since this class
- * implements the `RequiresMessageQueue<DequeBasedMessageQueueSemantics>` marker interface.
+ * implements the `RequiresMessageQueue&lt;DequeBasedMessageQueueSemantics&gt;` marker interface.
  * You can override the default mailbox provided when `DequeBasedMessageQueueSemantics` are requested via config:
  * <pre>
  *   akka.actor.mailbox.requirements {

akka-actor/src/main/scala/akka/actor/dsl/Inbox.scala

@@ -157,8 +157,8 @@ trait Inbox { this: ActorDSL.type ⇒
 
   /**
    * Create a new actor which will internally queue up messages it gets so that
-   * they can be interrogated with the [[akka.actor.dsl.Inbox!.Inbox!.receive]]
-   * and [[akka.actor.dsl.Inbox!.Inbox!.select]] methods. It will be created as
+   * they can be interrogated with the `akka.actor.dsl.Inbox!.Inbox!.receive`
+   * and `akka.actor.dsl.Inbox!.Inbox!.select` methods. It will be created as
    * a system actor in the ActorSystem which is implicitly (or explicitly)
    * supplied.
    */

akka-actor/src/main/scala/akka/dispatch/Dispatchers.scala

@@ -76,7 +76,7 @@ class Dispatchers(val settings: ActorSystem.Settings, val prerequisites: Dispatc
    * Returns a dispatcher as specified in configuration. Please note that this
    * method _may_ create and return a NEW dispatcher, _every_ call.
    *
-   * @throws ConfigurationException if the specified dispatcher cannot be found in the configuration
+   * Throws ConfigurationException if the specified dispatcher cannot be found in the configuration.
    */
   def lookup(id: String): MessageDispatcher = lookupConfigurator(id).dispatcher()
 

akka-actor/src/main/scala/akka/dispatch/Future.scala

@@ -41,7 +41,7 @@ object ExecutionContexts {
    * Returns a new ExecutionContextExecutorService which will delegate execution to the underlying ExecutorService,
    * and which will use the default error reporter.
    *
-   * @param executor the ExecutorService which will be used for the ExecutionContext
+   * @param executorService the ExecutorService which will be used for the ExecutionContext
    * @return a new ExecutionContext
    */
   def fromExecutorService(executorService: ExecutorService): ExecutionContextExecutorService =
@@ -51,7 +51,7 @@ object ExecutionContexts {
    * Returns a new ExecutionContextExecutorService which will delegate execution to the underlying ExecutorService,
    * and which will use the provided error reporter.
    *
-   * @param executor the ExecutorService which will be used for the ExecutionContext
+   * @param executorService the ExecutorService which will be used for the ExecutionContext
    * @param errorReporter a Procedure that will log any exceptions passed to it
    * @return a new ExecutionContext
    */
@@ -272,7 +272,7 @@ abstract class Recover[+T] extends japi.RecoverBridge[T] {
    * becomes completed with a failure.
    *
    * @return a successful value for the passed in failure
-   * @throws the passed in failure to propagate it.
+   * Throws the passed in failure to propagate it.
    *
    * Java API
    */
@@ -350,7 +350,7 @@ abstract class Mapper[-T, +R] extends scala.runtime.AbstractFunction1[T, R] {
   /**
    * Override this method if you need to throw checked exceptions
    *
-   * @throws UnsupportedOperation by default
+   * Throws UnsupportedOperation by default.
    */
   @throws(classOf[Throwable])
   def checkedApply(parameter: T): R = throw new UnsupportedOperationException("Mapper.checkedApply has not been implemented")

akka-actor/src/main/scala/akka/dispatch/sysmsg/SystemMessage.scala

@@ -182,7 +182,7 @@ private[akka] class EarliestFirstSystemMessageList(val head: SystemMessage) exte
  *
  * INTERNAL API
  *
- * ➡➡➡ NEVER SEND THE SAME SYSTEM MESSAGE OBJECT TO TWO ACTORS ⬅⬅⬅
+ * <b>NEVER SEND THE SAME SYSTEM MESSAGE OBJECT TO TWO ACTORS</b>
  */
 private[akka] sealed trait SystemMessage extends PossiblyHarmful with Serializable {
   // Next fields are only modifiable via the SystemMessageList value class

akka-actor/src/main/scala/akka/event/EventBusUnsubscribers.scala

@@ -51,7 +51,7 @@ private[akka] class EventStreamUnsubscriber(eventStream: EventStream, debug: Boo
  * INTERNAL API
  *
  * Provides factory for [[akka.event.EventStreamUnsubscriber]] actors with **unique names**.
- * This is needed if someone spins up more [[EventStream]]s using the same [[ActorSystem]],
+ * This is needed if someone spins up more [[EventStream]]s using the same [[akka.actor.ActorSystem]],
  * each stream gets it's own unsubscriber.
  */
 private[akka] object EventStreamUnsubscriber {