Unidoc directives for cluster md files #24689
Conversation
| @@ -30,7 +30,7 @@ You can send messages via the @unidoc[ClusterClient] to any actor in the cluster | |||
| in the @unidoc[DistributedPubSubMediator] used by the @unidoc[akka.cluster.client.ClusterReceptionist]. | |||
| The @unidoc[ClusterClientReceptionist] provides methods for registration of actors that | |||
| should be reachable from the client. Messages are wrapped in `ClusterClient.Send`, | |||
| @scala[@scaladoc[`ClusterClient.SendToAll`](akka.cluster.client.ClusterClient$)]@java[`ClusterClient.SendToAll`] or @scala[@scaladoc[`ClusterClient.Publish`](akka.cluster.client.ClusterClient$)]@java[`ClusterClient.Publish`]. | |||
| @scala[@scaladoc[`ClusterClient.SendToAll`](akka.cluster.client.ClusterClient$)]@java[@javadoc[`ClusterClient.SendToAll`](akka.cluster.client.ClusterClient)] or @scala[@scaladoc[`ClusterClient.Publish`](akka.cluster.client.ClusterClient$)]@java[@javadoc[`ClusterClient.Publish`](akka.cluster.client.ClusterClient)]. | |||
There was a problem hiding this comment.
cluster-client.md was taken care in an earlier PR, but for this specific one I realized it can be linked to https://doc.akka.io/japi/akka/2.5/?akka/cluster/client/ClusterClient.html
| When @ref[subscribing to cluster events](cluster-usage.md#cluster-subscriber) the `UnreachableMember` and | ||
| `ReachableMember` events are for observations within the own data center. The same data center as where the | ||
| When @ref[subscribing to cluster events](cluster-usage.md#cluster-subscriber) the @scala[@scaladoc[UnreachableMember](akka.cluster.ClusterEvent$)]@java[@javadoc[UnreachableMember](akka.cluster.ClusterEvent)] and | ||
| @scala[@scaladoc[ReachableMember](akka.cluster.ClusterEvent$)]@java[@javadoc[ReachableMember](akka.cluster.ClusterEvent)] events are for observations within the own data center. The same data center as where the |
There was a problem hiding this comment.
Similar to this comment unfortunately @unidoc directive does not work for classes inside object, as scaladoc and javadoc are rendered differently.
| @@ -16,7 +16,7 @@ In this context sharding means that actors with an identifier, so called entitie | |||
| can be automatically distributed across multiple nodes in the cluster. 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, which knows how | |||
| the messages via a @unidoc[ShardRegion](ShardRegion$) actor provided by this extension, which knows how | |||
There was a problem hiding this comment.
ShardRegion class is private, so linking to the object.
| case direct: Source.Direct => (s"@unidoc[${node.label}](${direct.value})", node.label, direct.value) | ||
| case ref: Source.Ref => (s"@unidoc[${node.label}](${ref.value})", node.label, ref.value) | ||
| case Source.Empty => (s"@unidoc[${node.label}]", node.label.split('.').last, node.label) | ||
| } |
There was a problem hiding this comment.
This is to handle two different syntax:
@unidoc[label](source)@unidoc[lable]
The former case is useful (e.g.) when you link to ShardRegion$ but don't want the $ appear in the label.
The latter shorthand syntax is convenient for the majority of the cases.
| } else { | ||
| throw new java.lang.IllegalStateException(s"fqcn not found by @unidoc[$fqcn]") | ||
| throw new java.lang.IllegalStateException(s"fqcn not found by $directive") |
There was a problem hiding this comment.
$directive is what users put in .md file, (i.e.) @unidoc[****](****) or @unidoc[*****]
akka-ci
added
tested
|
Test PASSed. |
|
I'm afraid I had to revert this since it broke the build (something the PR validation somehow did not notice/test). See: https://jenkins.akka.io:8498/job/akka-docs/2375/consoleFull You think you can look into it @richardimaoka ? |
| val (directive, label, source) = node.source match { | ||
| case direct: Source.Direct => (s"@unidoc[${node.label}](${direct.value})", node.label, direct.value) | ||
| case ref: Source.Ref => (s"@unidoc[${node.label}](${ref.value})", node.label, ref.value) | ||
| case Source.Empty => (s"@unidoc[${node.label}]", node.label.split('.').last, node.label) |
There was a problem hiding this comment.
Why .split('.').last already here?
|
Hm, strange that we didn't see that before - @richardimaoka this might be the time to introduce a separate sbt-paradox-unidoc project? I like your changes here and also did some work around objects in akka/akka-http#1903 that I hadn't had time to port to here yet, but it's also starting to get complicated enough that it'd be useful to have some unit tests :) Do you want to start on that? |
|
@raboof I am going to resume work on this. Could you add a bare-bone or an empty repository of the new sbt-paradox-unidoc project? |
|
That's great! I created https://github.com/lightbend/sbt-paradox-unidoc, let me know if there's anything you need. |
Part of #22904
This is to handle
@unidoc[label](source)syntax as in this comment in the same PR.Rendered HTML :
https://richard-akka-doc.firebaseapp.com/cluster-client.html
https://richard-akka-doc.firebaseapp.com/cluster-dc.html
https://richard-akka-doc.firebaseapp.com/cluster-metrics.html
https://richard-akka-doc.firebaseapp.com/cluster-sharding.html
https://richard-akka-doc.firebaseapp.com/cluster-singleton.html