Fix some non-standard comments (apache#939)

* Fix some non-standard comments

* revert

---------

Co-authored-by: Jiafu Tang <[email protected]>

Author: laglangyue

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.
    */

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.
    */

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.

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 =

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 = {

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.
    */

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

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.

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:
    * {{{
    * {

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[

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

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 =

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

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

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).

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](

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] = {

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