Fix some non-standard comments (apache#939)

laglangyue · web-flow · commit 6872f9c8b78a · 2024-01-14T12:47:51.000+01:00
* Fix some non-standard comments

* revert

---------

Co-authored-by: Jiafu Tang &lt;jiafu.tang@qq.com&gt;
diff --git a/actor/src/main/scala-2.12/org/apache/pekko/util/ByteString.scala b/actor/src/main/scala-2.12/org/apache/pekko/util/ByteString.scala
@@ -913,7 +913,7 @@ sealed abstract class ByteString extends IndexedSeq[Byte] with IndexedSeqOptimiz
    */
   def decodeString(charset: Charset): String
 
-  /*
+  /**
    * Returns a ByteString which is the binary representation of this ByteString
    * if this ByteString is Base64-encoded.
    */
diff --git a/actor/src/main/scala-3/org/apache/pekko/util/ByteString.scala b/actor/src/main/scala-3/org/apache/pekko/util/ByteString.scala
@@ -960,7 +960,7 @@ sealed abstract class ByteString
    */
   def decodeString(charset: Charset): String
 
-  /*
+  /**
    * Returns a ByteString which is the binary representation of this ByteString
    * if this ByteString is Base64-encoded.
    */
diff --git a/actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala b/actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala
@@ -1128,7 +1128,7 @@ private[pekko] class ActorSystemImpl(
       .get
   // #create-scheduler
 
-  /*
+  /**
    * This is called after the last actor has signaled its termination, i.e.
    * after the last dispatcher has had its chance to schedule its shutdown
    * action.
diff --git a/actor/src/main/scala/org/apache/pekko/actor/dungeon/Children.scala b/actor/src/main/scala/org/apache/pekko/actor/dungeon/Children.scala
@@ -145,7 +145,7 @@ private[pekko] trait Children { this: ActorCell =>
     _nextNameDoNotCallMeDirectly
   }
 
-  /*
+  /**
    * low level CAS helpers
    */
   private final def swapChildrenRefs(oldChildren: ChildrenContainer, newChildren: ChildrenContainer): Boolean =
diff --git a/actor/src/main/scala/org/apache/pekko/dispatch/AbstractDispatcher.scala b/actor/src/main/scala/org/apache/pekko/dispatch/AbstractDispatcher.scala
@@ -282,7 +282,7 @@ abstract class MessageDispatcher(val configurator: MessageDispatcherConfigurator
       mbox.suspend()
   }
 
-  /*
+  /**
    * After the call to this method, the dispatcher must begin any new message processing for the specified reference
    */
   protected[pekko] def resume(actor: ActorCell): Unit = {
diff --git a/actor/src/main/scala/org/apache/pekko/routing/RouterConfig.scala b/actor/src/main/scala/org/apache/pekko/routing/RouterConfig.scala
@@ -84,7 +84,7 @@ trait RouterConfig extends Serializable {
     case _                                                                    => false
   }
 
-  /*
+  /**
    * Specify that this router should stop itself when all routees have terminated (been removed).
    * By Default it is `true`, unless a `resizer` is used.
    */
@@ -244,7 +244,7 @@ trait Pool extends RouterConfig {
    */
   def props(routeeProps: Props): Props = routeeProps.withRouter(this)
 
-  /*
+  /**
    * Specify that this router should stop itself when all routees have terminated (been removed).
    * By Default it is `true`, unless a `resizer` is used.
    */
diff --git a/bench-jmh/src/main/scala/org/apache/pekko/stream/io/FileSourcesBenchmark.scala b/bench-jmh/src/main/scala/org/apache/pekko/stream/io/FileSourcesBenchmark.scala
@@ -104,7 +104,7 @@ class FileSourcesBenchmark {
     Await.result(h, 30.seconds)
   }
 
-  /*
+  /**
    * The previous status quo was very slow:
    * Benchmark                                         Mode  Cnt     Score      Error  Units
    * FileSourcesBenchmark.naive_ioSourceLinesIterator  avgt   20  7067.944 ± 1341.847  ms/op
diff --git a/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardRegion.scala b/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardRegion.scala
@@ -209,7 +209,7 @@ object ShardRegion {
    */
   @SerialVersionUID(1L) final case class Passivate(stopMessage: Any) extends ShardRegionCommand
 
-  /*
+  /**
    * Send this message to the `ShardRegion` actor to handoff all shards that are hosted by
    * the `ShardRegion` and then the `ShardRegion` actor will be stopped. You can `watch`
    * it to know when it is completed.
diff --git a/cluster/src/main/scala/org/apache/pekko/cluster/ClusterJmx.scala b/cluster/src/main/scala/org/apache/pekko/cluster/ClusterJmx.scala
@@ -45,7 +45,7 @@ trait ClusterNodeMBean {
    */
   def getUnreachable: String
 
-  /*
+  /**
    * JSON format of the status of all nodes in the cluster as follows:
    * {{{
    * {
diff --git a/distributed-data/src/main/scala/org/apache/pekko/cluster/ddata/protobuf/ReplicatedDataSerializer.scala b/distributed-data/src/main/scala/org/apache/pekko/cluster/ddata/protobuf/ReplicatedDataSerializer.scala
@@ -661,7 +661,7 @@ class ReplicatedDataSerializer(val system: ExtendedActorSystem)
       decrements = gcounterFromProto(pncounter.getDecrements))
   }
 
-  /*
+  /**
    * Convert a Map[A, B] to an Iterable[Entry] where Entry is the protobuf map entry.
    */
   private def getEntries[
diff --git a/multi-node-testkit/src/main/scala/org/apache/pekko/remote/testconductor/Conductor.scala b/multi-node-testkit/src/main/scala/org/apache/pekko/remote/testconductor/Conductor.scala
@@ -444,7 +444,7 @@ private[pekko] class Controller(private var initialParticipants: Int, controller
     settings.ServerSocketWorkerPoolSize,
     new ConductorHandler(settings.QueryTimeout, self, Logging(context.system, classOf[ConductorHandler])))
 
-  /*
+  /**
    * Supervision of the BarrierCoordinator means to catch all his bad emotions
    * and sometimes console him (BarrierEmpty, BarrierTimeout), sometimes tell
    * him to hate the world (WrongBarrier, DuplicateNode, ClientLost). The latter shall help
diff --git a/osgi/src/main/scala/org/apache/pekko/osgi/BundleDelegatingClassLoader.scala b/osgi/src/main/scala/org/apache/pekko/osgi/BundleDelegatingClassLoader.scala
@@ -31,7 +31,7 @@ import org.apache.pekko.util.ccompat.JavaConverters._
  */
 object BundleDelegatingClassLoader {
 
-  /*
+  /**
    * Create a bundle delegating ClassLoader for the bundle context's bundle
    */
   def apply(context: BundleContext): BundleDelegatingClassLoader =
diff --git a/remote/src/main/scala/org/apache/pekko/remote/RemoteActorRefProvider.scala b/remote/src/main/scala/org/apache/pekko/remote/RemoteActorRefProvider.scala
@@ -108,7 +108,7 @@ private[pekko] object RemoteActorRefProvider {
 
   }
 
-  /*
+  /**
    * Remoting wraps messages destined to a remote host in a remoting specific envelope: EndpointManager.Send
    * As these wrapped messages might arrive to the dead letters of an EndpointWriter, they need to be unwrapped
    * and handled as dead letters to the original (remote) destination. Without this special case, DeathWatch related
diff --git a/remote/src/main/scala/org/apache/pekko/remote/transport/PekkoProtocolTransport.scala b/remote/src/main/scala/org/apache/pekko/remote/transport/PekkoProtocolTransport.scala
@@ -243,21 +243,21 @@ private[remote] class PekkoProtocolHandle(
 private[remote] object ProtocolStateActor {
   sealed trait AssociationState
 
-  /*
+  /**
    * State when the underlying transport is not yet initialized
    * State data can be OutboundUnassociated
    */
   case object Closed extends AssociationState
 
-  /*
+  /**
    * State when the underlying transport is initialized, there is an association present, and we are waiting
    * for the first message (has to be CONNECT if inbound).
    * State data can be OutboundUnderlyingAssociated (for outbound associations) or InboundUnassociated (for inbound
    * when upper layer is not notified yet)
    */
   case object WaitHandshake extends AssociationState
 
-  /*
+  /**
    * State when the underlying transport is initialized and the handshake succeeded.
    * If the upper layer did not yet provided a handler for incoming messages, state data is AssociatedWaitHandler.
    * If everything is initialized, the state data is HandlerReady
diff --git a/stream/src/main/scala/org/apache/pekko/stream/impl/Sinks.scala b/stream/src/main/scala/org/apache/pekko/stream/impl/Sinks.scala
@@ -85,7 +85,7 @@ import pekko.util.ccompat._
 @InternalApi private[pekko] class PublisherSink[In](val attributes: Attributes, shape: SinkShape[In])
     extends SinkModule[In, Publisher[In]](shape) {
 
-  /*
+  /**
    * This method is the reason why SinkModule.create may return something that is
    * not a Subscriber: a VirtualPublisher is used in order to avoid the immediate
    * subscription a VirtualProcessor would perform (and it also saves overhead).
diff --git a/stream/src/main/scala/org/apache/pekko/stream/javadsl/Source.scala b/stream/src/main/scala/org/apache/pekko/stream/javadsl/Source.scala
@@ -704,7 +704,7 @@ object Source {
     new Source(scaladsl.Source.zipN(seq).map(_.asJava))
   }
 
-  /*
+  /**
    * Combine the elements of multiple streams into a stream of lists using a combiner function.
    */
   def zipWithN[T, O](
diff --git a/stream/src/main/scala/org/apache/pekko/stream/scaladsl/Source.scala b/stream/src/main/scala/org/apache/pekko/stream/scaladsl/Source.scala
@@ -815,7 +815,7 @@ object Source {
   def zipN[T](sources: immutable.Seq[Source[T, _]]): Source[immutable.Seq[T], NotUsed] =
     zipWithN(ConstantFun.scalaIdentityFunction[immutable.Seq[T]])(sources).addAttributes(DefaultAttributes.zipN)
 
-  /*
+  /**
    * Combine the elements of multiple streams into a stream of sequences using a combiner function.
    */
   def zipWithN[T, O](zipper: immutable.Seq[T] => O)(sources: immutable.Seq[Source[T, _]]): Source[O, NotUsed] = {
diff --git a/testkit/src/main/scala/org/apache/pekko/testkit/CallingThreadDispatcher.scala b/testkit/src/main/scala/org/apache/pekko/testkit/CallingThreadDispatcher.scala
@@ -110,7 +110,7 @@ private[testkit] class CallingThreadDispatcherQueues extends Extension {
     queues -= mbox
   }
 
-  /*
+  /**
    * This method must be called with "own" being this thread's queue for the
    * given mailbox. When this method returns, the queue will be entered
    * (active).
@@ -248,7 +248,7 @@ class CallingThreadDispatcher(_configurator: MessageDispatcherConfigurator) exte
 
   protected[pekko] override def executeTask(invocation: TaskInvocation): Unit = { invocation.run() }
 
-  /*
+  /**
    * This method must be called with this thread's queue.
    *
    * If the catch block is executed, then a non-empty mailbox may be stalled as

Original file line number	Diff line number	Diff line change
`@@ -145,7 +145,7 @@ private[pekko] trait Children { this: ActorCell =>`
`145`	`145`	`_nextNameDoNotCallMeDirectly`
`146`	`146`	`}`
`147`	`147`
`148`		`- /*`
	`148`	`+ /**`
`149`	`149`	`* low level CAS helpers`
`150`	`150`	`*/`
`151`	`151`	`private final def swapChildrenRefs(oldChildren: ChildrenContainer, newChildren: ChildrenContainer): Boolean =`
Original file line number	Diff line number	Diff line change
`@@ -282,7 +282,7 @@ abstract class MessageDispatcher(val configurator: MessageDispatcherConfigurator`
`282`	`282`	`mbox.suspend()`
`283`	`283`	`}`
`284`	`284`
`285`		`- /*`
	`285`	`+ /**`
`286`	`286`	`* After the call to this method, the dispatcher must begin any new message processing for the specified reference`
`287`	`287`	`*/`
`288`	`288`	`protected[pekko] def resume(actor: ActorCell): Unit = {`
Original file line number	Diff line number	Diff line change
`@@ -104,7 +104,7 @@ class FileSourcesBenchmark {`
`104`	`104`	`Await.result(h, 30.seconds)`
`105`	`105`	`}`
`106`	`106`
`107`		`- /*`
	`107`	`+ /**`
`108`	`108`	`* The previous status quo was very slow:`
`109`	`109`	`* Benchmark Mode Cnt Score Error Units`
`110`	`110`	`* FileSourcesBenchmark.naive_ioSourceLinesIterator avgt 20 7067.944 ± 1341.847 ms/op`
Original file line number	Diff line number	Diff line change
`@@ -661,7 +661,7 @@ class ReplicatedDataSerializer(val system: ExtendedActorSystem)`
`661`	`661`	`decrements = gcounterFromProto(pncounter.getDecrements))`
`662`	`662`	`}`
`663`	`663`
`664`		`- /*`
	`664`	`+ /**`
`665`	`665`	`* Convert a Map[A, B] to an Iterable[Entry] where Entry is the protobuf map entry.`
`666`	`666`	`*/`
`667`	`667`	`private def getEntries[`