From 8e952fa3a4f2da2a7f7d881690e23dba22002276 Mon Sep 17 00:00:00 2001 From: Arnout Engelen Date: Wed, 10 Jul 2019 08:11:31 +0200 Subject: [PATCH] Update paradox-apidoc (#27270) For easier referencing of typed javadsl/scaladsl classes --- .../paradox/project/migration-guide-2.5.x-2.6.x.md | 2 +- akka-docs/src/main/paradox/typed/actor-lifecycle.md | 10 +++++----- akka-docs/src/main/paradox/typed/distributed-data.md | 8 ++++---- akka-docs/src/main/paradox/typed/persistence.md | 4 ++-- akka-docs/src/main/paradox/typed/testing.md | 6 +++--- project/plugins.sbt | 2 +- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md b/akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md index 2688245243..6bd2ea2b14 100644 --- a/akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md +++ b/akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md @@ -391,7 +391,7 @@ made before finalizing the APIs. Compared to Akka 2.5.x the source incompatible they were redundant with corresponding @scala[scaladsl.Behaviors.x]@java[javadsl.Behaviors.x]. * `ActorContext` parameter removed in `javadsl.ReceiveBuilder` for the functional style in Java. Use `Behaviors.setup` to retrieve `ActorContext`, and use an enclosing class to hold initialization parameters and `ActorContext`. -* Java @apidoc[akka.cluster.sharding.typed.javadsl.EntityRef] ask timeout now takes a `java.time.Duration` rather than a @apidoc[Timeout] +* Java @javadoc[EntityRef](akka.cluster.sharding.typed.javadsl.EntityRef) ask timeout now takes a `java.time.Duration` rather than a @apidoc[Timeout] * Changed method signature for `EventAdapter.fromJournal` and support for `manifest` in `EventAdapter`. * `BehaviorInterceptor`, `Behaviors.monitor`, `Behaviors.withMdc` and @scala[`widen`]@java[`Behaviors.widen`] takes a @scala[`ClassTag` parameter (probably source compatible)]@java[`interceptMessageClass` parameter]. diff --git a/akka-docs/src/main/paradox/typed/actor-lifecycle.md b/akka-docs/src/main/paradox/typed/actor-lifecycle.md index acd643b4d0..fbef635693 100644 --- a/akka-docs/src/main/paradox/typed/actor-lifecycle.md +++ b/akka-docs/src/main/paradox/typed/actor-lifecycle.md @@ -45,14 +45,14 @@ Java Many of the methods in `ActorContext` are not thread-safe and -* Must not be accessed by threads from @scala[`scala.concurrent.Future`]@java[`java.util.concurrent.CompletionStage`] callbacks +* Must not be accessed by threads from @scala[`scala.concurrent.Future`]@java[`java.util.concurrent.CompletionStage`] callbacks * Must not be shared between several actor instances * Should only be used in the ordinary actor message processing thread ### The Guardian Actor -The root actor, also called the guardian actor, is created along with the `ActorSystem`. Messages sent to the actor -system are directed to the root actor. The root actor is defined by the behavior used to create the `ActorSystem`, +The root actor, also called the guardian actor, is created along with the `ActorSystem`. Messages sent to the actor +system are directed to the root actor. The root actor is defined by the behavior used to create the `ActorSystem`, named `HelloWorldMain.main` in the example below: Scala @@ -68,12 +68,12 @@ In the untyped counter part, the @apidoc[akka.actor.ActorSystem], the root actor could spawn top-level actors from the outside of the `ActorSystem` using `actorOf`. @ref:[SpawnProtocol](#spawnprotocol) is a tool that mimics the old style of starting up actors. -@@@ +@@@ ### Spawning Children -Child actors are spawned with @scala[@apidoc[akka.actor.typed.scaladsl.ActorContext]]@java[@apidoc[akka.actor.typed.javadsl.ActorContext]]'s `spawn`. +Child actors are spawned with @apidoc[typed.*.ActorContext]'s `spawn`. In the example below, when the root actor is started, it spawns a child actor described by the behavior `HelloWorld.greeter`. Additionally, when the root actor receives a `Start` message, it creates a child actor defined by the behavior `HelloWorldBot.bot`: diff --git a/akka-docs/src/main/paradox/typed/distributed-data.md b/akka-docs/src/main/paradox/typed/distributed-data.md index 66420c436d..10b6e56030 100644 --- a/akka-docs/src/main/paradox/typed/distributed-data.md +++ b/akka-docs/src/main/paradox/typed/distributed-data.md @@ -33,12 +33,12 @@ out-of-date value. ## Using the Replicator -The @scala[@apidoc[akka.cluster.ddata.typed.scaladsl.Replicator]]@java[@apidoc[akka.cluster.ddata.typed.javadsl.Replicator]] +The @apidoc[typed.*.Replicator] actor provides the API for interacting with the data and is accessed through the extension -@scala[@apidoc[akka.cluster.ddata.typed.scaladsl.DistributedData]]@java[@apidoc[akka.cluster.ddata.typed.javadsl.DistributedData]]. +@apidoc[typed.*.DistributedData]. -The messages for the replicator, such as `Replicator.Update` are defined in @scala[`akka.cluster.ddata.typed.scaladsl.Replicator`] -@java[`akka.cluster.ddata.typed.scaladsl.Replicator`] but the actual CRDTs are the +The messages for the replicator, such as `Replicator.Update` are defined in @apidoc[typed.*.Replicator] +but the actual CRDTs are the same as in untyped, for example `akka.cluster.ddata.GCounter`. This will require a @scala[implicit] `akka.cluster.ddata.SelfUniqueAddress.SelfUniqueAddress`, available from @scala[`implicit val node = DistributedData(system).selfUniqueAddress`]@java[SelfUniqueAddress node = DistributedData.get(system).selfUniqueAddress();]. diff --git a/akka-docs/src/main/paradox/typed/persistence.md b/akka-docs/src/main/paradox/typed/persistence.md index b0a40f1908..eb0546be0f 100644 --- a/akka-docs/src/main/paradox/typed/persistence.md +++ b/akka-docs/src/main/paradox/typed/persistence.md @@ -25,7 +25,7 @@ works and assumes you know what is meant by `Command`, `Event` and `State`. ## Example -Let's start with a simple example. The minimum required for a `EventSourcedBehavior` is: +Let's start with a simple example. The minimum required for a @apidoc[EventSourcedBehavior] is: Scala : @@snip [BasicPersistentBehaviorCompileOnly.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/BasicPersistentBehaviorCompileOnly.scala) { #structure } @@ -144,7 +144,7 @@ interpreted correctly on replay. Cluster Sharding ensures that there is only one ## Accessing the ActorContext -If the `EventSourcedBehavior` needs to use the `ActorContext`, for example to spawn child actors, it can be obtained by +If the @apidoc[EventSourcedBehavior] needs to use the @apidoc[typed.*.ActorContext], for example to spawn child actors, it can be obtained by wrapping construction with `Behaviors.setup`: Scala diff --git a/akka-docs/src/main/paradox/typed/testing.md b/akka-docs/src/main/paradox/typed/testing.md index 0b88587430..d1cb69b230 100644 --- a/akka-docs/src/main/paradox/typed/testing.md +++ b/akka-docs/src/main/paradox/typed/testing.md @@ -27,7 +27,7 @@ We recommend using Akka TestKit Typed with ScalaTest: ## Introduction Testing can either be done asynchronously using a real @apidoc[akka.actor.typed.ActorSystem] or synchronously on the testing thread using the -@scala[@apidoc[akka.actor.testkit.typed.scaladsl.BehaviorTestKit]]@java[@apidoc[akka.actor.testkit.typed.javadsl.BehaviorTestKit]]. +@apidoc[typed.*.BehaviorTestKit]. For testing logic in a @apidoc[Behavior] in isolation synchronous testing is preferred, but the features that can be tested are limited. For testing interactions between multiple actors a more realistic asynchronous test is preferred. @@ -140,7 +140,7 @@ Java @@@ div { .group-java } -If you are using JUnit you can use @apidoc[akka.actor.testkit.typed.javadsl.TestKitJunitResource] to have the async test kit automatically +If you are using JUnit you can use @javadoc[TestKitJunitResource](akka.actor.testkit.typed.javadsl.TestKitJunitResource) to have the async test kit automatically shutdown when the test is complete. Note that the dependency on JUnit is marked as optional from the test kit module, so your project must explicitly include @@ -150,7 +150,7 @@ a dependency on JUnit to use this. @@@ div { .group-scala } -If you are using ScalaTest you can extend @apidoc[akka.actor.testkit.typed.scaladsl.ScalaTestWithActorTestKit] to +If you are using ScalaTest you can extend @scaladoc[ScalaTestWithActorTestKit](akka.actor.testkit.typed.scaladsl.ScalaTestWithActorTestKit) to have the async test kit automatically shutdown when the test is complete. This is done in `afterAll` from the `BeforeAndAfterAll` trait. If you override that method you should call `super.afterAll` to shutdown the test kit. diff --git a/project/plugins.sbt b/project/plugins.sbt index f370a672bb..eac0bf281c 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -16,7 +16,7 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.3.15") addSbtPlugin("io.spray" % "sbt-boilerplate" % "0.6.1") addSbtPlugin("com.timushev.sbt" % "sbt-updates" % "0.3.4") addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.18") -addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-apidoc" % "0.1+9-d846d815") +addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-apidoc" % "0.2") addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.5.4") addSbtPlugin("com.lightbend" % "sbt-whitesource" % "0.1.13") addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "1.0.0")