This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new 52234c0199 Fix unresolvable scaladoc links to the ShardRegion actor
#353 (#3064)
52234c0199 is described below
commit 52234c019909ceaa23b59da55f2190d7e48d6635
Author: Arun Selvamani <[email protected]>
AuthorDate: Sun Jun 14 00:50:29 2026 -0700
Fix unresolvable scaladoc links to the ShardRegion actor #353 (#3064)
Motivation:
`sbt unidoc` emits "Could not find any member to link for "ShardRegion""
warnings across cluster-sharding. The bare `[[ShardRegion]]` links target
the `ShardRegion` actor, which is the `private[pekko] class ShardRegion`
and therefore is not part of the generated API docs, so scaladoc cannot
resolve the link.
Modification:
Replace the bare `[[ShardRegion]]` actor references with backticked
`ShardRegion` in ClusterSharding.scala, ShardRegion.scala, and
ShardCoordinator.scala. This matches the existing local style (these files
already refer to the actor as `ShardRegion` in prose) and the approach used
in #2780. Qualified links that resolve correctly (e.g.
`[[ShardRegion.Passivate]]`, `[[ShardRegion.MessageExtractor]]`) are left
untouched.
Result:
The 18 "Could not find any member to link for "ShardRegion"" warnings in
the cluster-sharding module are gone.
Tests:
- sbt -Dpekko.scaladoc.diagrams=false "cluster-sharding/doc" - success, 0
ShardRegion link warnings (docs only)
- sbt "cluster-sharding/scalafmtCheck" - success
- git diff --check - clean
References:
Refs #353
Co-authored-by: Arun Selvamani <[email protected]>
---
.../pekko/cluster/sharding/ClusterSharding.scala | 66 +++++++++++-----------
.../pekko/cluster/sharding/ShardCoordinator.scala | 8 +--
.../pekko/cluster/sharding/ShardRegion.scala | 8 +--
3 files changed, 41 insertions(+), 41 deletions(-)
diff --git
a/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ClusterSharding.scala
b/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ClusterSharding.scala
index d8515977a4..bb393b299a 100755
---
a/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ClusterSharding.scala
+++
b/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ClusterSharding.scala
@@ -72,7 +72,7 @@ import pekko.util.ByteString
* '''ShardRegion''':
* Each entity actor runs only at one place, and messages can be sent to the
entity without
* requiring the sender to know the location of the destination actor. This is
achieved by
- * sending the messages via a [[ShardRegion]] actor, provided by this
extension. The [[ShardRegion]]
+ * sending the messages via a `ShardRegion` actor, provided by this extension.
The `ShardRegion`
* knows the shard mappings and routes inbound messages to the entity with the
entity id.
* Messages to the entities are always sent via the local `ShardRegion`.
* The `ShardRegion` actor is started on each node in the cluster, or group of
nodes
@@ -198,10 +198,10 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Scala API: Register a named entity type by defining the
[[pekko.actor.Props]] of the entity actor
- * and functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * and functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[shardRegion]] method.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the roles of
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the roles of
* the current cluster node and the role specified in
[[ClusterShardingSettings]] passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -219,7 +219,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* rebalancing logic
* @param handOffStopMessage the message that will be sent to entities when
they are to be stopped
* for a rebalance or graceful shutdown of a `ShardRegion`, e.g.
`PoisonPill`.
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(
typeName: String,
@@ -242,10 +242,10 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Scala API: Register a named entity type by defining the
[[pekko.actor.Props]] of the entity actor
- * and functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * and functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[shardRegion]] method.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the roles of
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the roles of
* the current cluster node and the role specified in
[[ClusterShardingSettings]] passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -262,7 +262,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* rebalancing logic
* @param handOffStopMessage the message that will be sent to entities when
they are to be stopped
* for a rebalance or graceful shutdown of a `ShardRegion`, e.g.
`PoisonPill`.
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(
typeName: String,
@@ -335,13 +335,13 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Register a named entity type by defining the [[pekko.actor.Props]] of the
entity actor and
- * functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[shardRegion]] method.
*
* The default shard allocation strategy
[[ShardCoordinator.LeastShardAllocationStrategy]]
* is used. [[pekko.actor.PoisonPill]] is used as `handOffStopMessage`.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the
* node roles and the role specified in the [[ClusterShardingSettings]]
passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -355,7 +355,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* be `unhandled`, i.e. posted as `Unhandled` messages on the event stream
* @param extractShardId function to determine the shard id for an incoming
message, only messages
* that passed the `extractEntityId` will be used
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(
typeName: String,
@@ -371,13 +371,13 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Register a named entity type by defining the [[pekko.actor.Props]] of the
entity actor and
- * functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[shardRegion]] method.
*
* The default shard allocation strategy
[[ShardCoordinator.LeastShardAllocationStrategy]]
* is used. [[pekko.actor.PoisonPill]] is used as `handOffStopMessage`.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the
* node roles and the role specified in the [[ClusterShardingSettings]]
passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -390,7 +390,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* be `unhandled`, i.e. posted as `Unhandled` messages on the event stream
* @param extractShardId function to determine the shard id for an incoming
message, only messages
* that passed the `extractEntityId` will be used
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(
typeName: String,
@@ -403,10 +403,10 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Java/Scala API: Register a named entity type by defining the
[[pekko.actor.Props]] of the entity actor
- * and functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * and functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[#shardRegion]] method.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the
* node roles and the role specified in the [[ClusterShardingSettings]]
passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -421,7 +421,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* rebalancing logic
* @param handOffStopMessage the message that will be sent to entities when
they are to be stopped
* for a rebalance or graceful shutdown of a `ShardRegion`, e.g.
`PoisonPill`.
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(
typeName: String,
@@ -446,13 +446,13 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Java/Scala API: Register a named entity type by defining the
[[pekko.actor.Props]] of the entity actor
- * and functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * and functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[#shardRegion]] method.
*
* The default shard allocation strategy
[[ShardCoordinator.LeastShardAllocationStrategy]]
* is used. [[pekko.actor.PoisonPill]] is used as `handOffStopMessage`.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the
* node roles and the role specified in the [[ClusterShardingSettings]]
passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -463,7 +463,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* @param settings configuration settings, see [[ClusterShardingSettings]]
* @param messageExtractor functions to extract the entity id, shard id, and
the message to send to the
* entity from the incoming message
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(
typeName: String,
@@ -478,13 +478,13 @@ class ClusterSharding(system: ExtendedActorSystem)
extends Extension {
/**
* Java/Scala API: Register a named entity type by defining the
[[pekko.actor.Props]] of the entity actor
- * and functions to extract entity and shard identifier from messages. The
[[ShardRegion]] actor
+ * and functions to extract entity and shard identifier from messages. The
`ShardRegion` actor
* for this type can later be retrieved with the [[#shardRegion]] method.
*
* The default shard allocation strategy
[[ShardCoordinator.LeastShardAllocationStrategy]]
* is used. [[pekko.actor.PoisonPill]] is used as `handOffStopMessage`.
*
- * This method will start a [[ShardRegion]] in proxy mode when there is no
match between the
+ * This method will start a `ShardRegion` in proxy mode when there is no
match between the
* node roles and the role specified in the [[ClusterShardingSettings]]
passed to this method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -494,7 +494,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* @param entityProps the `Props` of the entity actors that will be created
by the `ShardRegion`
* @param messageExtractor functions to extract the entity id, shard id, and
the message to send to the
* entity from the incoming message
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def start(typeName: String, entityProps: Props, messageExtractor:
ShardRegion.MessageExtractor): ActorRef = {
start(typeName, entityProps, ClusterShardingSettings(system),
messageExtractor)
@@ -503,7 +503,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
/**
* Scala API: Register a named entity type `ShardRegion` on this node that
will run in proxy only mode,
* i.e. it will delegate messages to other `ShardRegion` actors on other
nodes, but not host any
- * entity actors itself. The [[ShardRegion]] actor for this type can later
be retrieved with the
+ * entity actors itself. The `ShardRegion` actor for this type can later be
retrieved with the
* [[#shardRegion]] method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -517,7 +517,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* be `unhandled`, i.e. posted as `Unhandled` messages on the event stream
* @param extractShardId function to determine the shard id for an incoming
message, only messages
* that passed the `extractEntityId` will be used
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def startProxy(
typeName: String,
@@ -529,7 +529,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
/**
* Scala API: Register a named entity type `ShardRegion` on this node that
will run in proxy only mode,
* i.e. it will delegate messages to other `ShardRegion` actors on other
nodes, but not host any
- * entity actors itself. The [[ShardRegion]] actor for this type can later
be retrieved with the
+ * entity actors itself. The `ShardRegion` actor for this type can later be
retrieved with the
* [[#shardRegion]] method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -545,7 +545,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* be `unhandled`, i.e. posted as `Unhandled` messages on the event stream
* @param extractShardId function to determine the shard id for an incoming
message, only messages
* that passed the `extractEntityId` will be used
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def startProxy(
typeName: String,
@@ -578,7 +578,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
/**
* Java/Scala API: Register a named entity type `ShardRegion` on this node
that will run in proxy only mode,
* i.e. it will delegate messages to other `ShardRegion` actors on other
nodes, but not host any
- * entity actors itself. The [[ShardRegion]] actor for this type can later
be retrieved with the
+ * entity actors itself. The `ShardRegion` actor for this type can later be
retrieved with the
* [[#shardRegion]] method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -589,7 +589,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* If the role is not specified all nodes in the cluster are used.
* @param messageExtractor functions to extract the entity id, shard id, and
the message to send to the
* entity from the incoming message
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def startProxy(typeName: String, role: Optional[String], messageExtractor:
ShardRegion.MessageExtractor): ActorRef =
startProxy(typeName, role, dataCenter = Optional.empty(), messageExtractor)
@@ -597,7 +597,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
/**
* Java/Scala API: Register a named entity type `ShardRegion` on this node
that will run in proxy only mode,
* i.e. it will delegate messages to other `ShardRegion` actors on other
nodes, but not host any
- * entity actors itself. The [[ShardRegion]] actor for this type can later
be retrieved with the
+ * entity actors itself. The `ShardRegion` actor for this type can later be
retrieved with the
* [[#shardRegion]] method.
*
* Some settings can be configured as described in the
`pekko.cluster.sharding` section
@@ -610,7 +610,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
* If None then the same data center as current node.
* @param messageExtractor functions to extract the entity id, shard id, and
the message to send to the
* entity from the incoming message
- * @return the actor ref of the [[ShardRegion]] that is to be responsible
for the shard
+ * @return the actor ref of the `ShardRegion` that is to be responsible for
the shard
*/
def startProxy(
typeName: String,
@@ -637,7 +637,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
def getShardTypeNames: java.util.Set[String] = regions.keySet()
/**
- * Retrieve the actor reference of the [[ShardRegion]] actor responsible for
the named entity type.
+ * Retrieve the actor reference of the `ShardRegion` actor responsible for
the named entity type.
* The entity type must be registered with the [[#start]] or [[#startProxy]]
method before it
* can be used here. Messages to the entity is always sent via the
`ShardRegion`.
*/
@@ -655,7 +655,7 @@ class ClusterSharding(system: ExtendedActorSystem) extends
Extension {
}
/**
- * Retrieve the actor reference of the [[ShardRegion]] actor that will act
as a proxy to the
+ * Retrieve the actor reference of the `ShardRegion` actor that will act as
a proxy to the
* named entity type running in another data center. A proxy within the same
data center can be accessed
* with [[#shardRegion]] instead of this method. The entity type must be
registered with the
* [[#startProxy]] method before it can be used here. Messages to the entity
is always sent
@@ -717,7 +717,7 @@ private[pekko] object ClusterShardingGuardian {
}
/**
- * INTERNAL API. [[ShardRegion]] and [[ShardCoordinator]] actors are created
as children
+ * INTERNAL API. `ShardRegion` and [[ShardCoordinator]] actors are created as
children
* of this actor.
*/
private[pekko] class ClusterShardingGuardian extends Actor {
diff --git
a/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardCoordinator.scala
b/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardCoordinator.scala
index b079f98d43..b353bd7ede 100644
---
a/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardCoordinator.scala
+++
b/cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardCoordinator.scala
@@ -141,12 +141,12 @@ object ShardCoordinator {
/**
* Invoked when the location of a new shard is to be decided.
*
- * @param requester actor reference to the [[ShardRegion]]
that requested the location of the
+ * @param requester actor reference to the `ShardRegion`
that requested the location of the
* shard, can be returned if preference
should be given to the node where the shard was first accessed
* @param shardId the id of the shard to allocate
* @param currentShardAllocations all actor refs to `ShardRegion` and
their current allocated shards,
* in the order they were allocated
- * @return a `Future` of the actor ref of the [[ShardRegion]] that is to
be responsible for the shard, must be one of
+ * @return a `Future` of the actor ref of the `ShardRegion` that is to be
responsible for the shard, must be one of
* the references included in the `currentShardAllocations`
parameter
*/
def allocateShard(
@@ -227,12 +227,12 @@ object ShardCoordinator {
/**
* Invoked when the location of a new shard is to be decided.
*
- * @param requester actor reference to the [[ShardRegion]]
that requested the location of the
+ * @param requester actor reference to the `ShardRegion`
that requested the location of the
* shard, can be returned if preference
should be given to the node where the shard was first accessed
* @param shardId the id of the shard to allocate
* @param currentShardAllocations all actor refs to `ShardRegion` and
their current allocated shards,
* in the order they were allocated
- * @return a `Future` of the actor ref of the [[ShardRegion]] that is to
be responsible for the shard, must be one of
+ * @return a `Future` of the actor ref of the `ShardRegion` that is to be
responsible for the shard, must be one of
* the references included in the `currentShardAllocations`
parameter
*/
def allocateShard(
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
index ca59e57c91..05e04e5799 100644
---
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
@@ -50,7 +50,7 @@ object ShardRegion {
/**
* INTERNAL API
- * Factory method for the [[pekko.actor.Props]] of the [[ShardRegion]] actor.
+ * Factory method for the [[pekko.actor.Props]] of the `ShardRegion` actor.
*/
private[pekko] def props(
typeName: String,
@@ -75,7 +75,7 @@ object ShardRegion {
/**
* INTERNAL API
- * Factory method for the [[pekko.actor.Props]] of the [[ShardRegion]] actor
+ * Factory method for the [[pekko.actor.Props]] of the `ShardRegion` actor
* when using it in proxy only mode.
*/
private[pekko] def proxyProps(
@@ -113,7 +113,7 @@ object ShardRegion {
type Msg = Any
/**
- * Interface of the partial function used by the [[ShardRegion]] to
+ * Interface of the partial function used by the `ShardRegion` to
* extract the entity id and the message to send to the entity from an
* incoming message. The implementation is application specific.
* If the partial function does not match the message will be
@@ -125,7 +125,7 @@ object ShardRegion {
type ExtractEntityId = PartialFunction[Msg, (EntityId, Msg)]
/**
- * Interface of the function used by the [[ShardRegion]] to
+ * Interface of the function used by the `ShardRegion` to
* extract the shard id from an incoming message.
* Only messages that passed the [[ExtractEntityId]] will be used
* as input to this function.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
