Refactor example to make it easier to copy-paste #29578 (#29860)

* Refactor example to make it clear #29578

Restructure example

* Fix formatting

* Right formatting to disable format checker

akka-actor-typed-tests/src/test/java/jdocs/akka/typed/RouterTest.java

@@ -25,7 +25,7 @@ import akka.actor.typed.receptionist.ServiceKey;
 
 public class RouterTest {
 
-  static // #pool
+  static // #routee
   class Worker {
     interface Command {}
 
@@ -54,12 +54,14 @@ public class RouterTest {
     }
   }
 
-  // #pool
+  // #routee
 
   static Behavior<Void> showPoolRouting() {
-    return Behaviors.setup(
-        context -> {
+    return
     // #pool
+    // This would be defined within your actor class
+    Behaviors.setup(
+        context -> {
           int poolSize = 4;
           PoolRouter<Worker.Command> pool =
               Routers.pool(
@@ -87,7 +89,10 @@ public class RouterTest {
           // #strategy
 
           return Behaviors.empty();
+          // #pool
         });
+    // #pool
+
   }
 
   static Behavior<Void> showGroupRouting() {
@@ -95,9 +100,11 @@ public class RouterTest {
     ServiceKey<Worker.Command> serviceKey = ServiceKey.create(Worker.Command.class, "log-worker");
 
     // #group
-    return Behaviors.setup(
-        context -> {
+    return
     // #group
+    Behaviors.setup(
+        context -> {
+
           // this would likely happen elsewhere - if we create it locally we
           // can just as well use a pool
           ActorRef<Worker.Command> worker = context.spawn(Worker.create(), "worker");
@@ -106,15 +113,16 @@ public class RouterTest {
           GroupRouter<Worker.Command> group = Routers.group(serviceKey);
           ActorRef<Worker.Command> router = context.spawn(group, "worker-group");
 
-          // the group router will stash messages until it sees the first listing of registered
+          // the group router will stash messages until it sees the first listing of
+          // registered
           // services from the receptionist, so it is safe to send messages right away
           for (int i = 0; i < 10; i++) {
             router.tell(new Worker.DoLog("msg " + i));
           }
-          // #group
 
           return Behaviors.empty();
         });
+    // #group
   }
 
   public static void main(String[] args) {

akka-actor-typed-tests/src/test/scala/docs/akka/typed/RouterSpec.scala

@@ -10,13 +10,12 @@ import akka.actor.testkit.typed.scaladsl.{ LogCapturing, ScalaTestWithActorTestK
 import akka.actor.typed.{ Behavior, SupervisorStrategy }
 import akka.actor.typed.receptionist.{ Receptionist, ServiceKey }
 import akka.actor.typed.scaladsl.{ Behaviors, Routers }
-import org.scalatest.wordspec.AnyWordSpecLike
 
 // #pool
-
+import org.scalatest.wordspec.AnyWordSpecLike
 object RouterSpec {
 
-  // #pool
+  // #routee
   object Worker {
     sealed trait Command
     case class DoLog(text: String) extends Command
@@ -32,11 +31,14 @@ object RouterSpec {
     }
   }
 
-  // #pool
+  // #routee
+  // This code is extra indented for visualization purposes
+  // format: OFF
   // #group
         val serviceKey = ServiceKey[Worker.Command]("log-worker")
 
   // #group
+  // format: ON
 }
 
 class RouterSpec extends ScalaTestWithActorTestKit("akka.loglevel=warning") with AnyWordSpecLike with LogCapturing {
@@ -54,11 +56,14 @@ class RouterSpec extends ScalaTestWithActorTestKit("akka.loglevel=warning") with
         def DoLog(text: String) = RouterSpec.Worker.DoLog(text)
       }
 
-      spawn(Behaviors.setup[Unit] { ctx =>
+      spawn(
         // #pool
-        val pool = Routers.pool(poolSize = 4)(
+        // This would be defined within your actor object
+        Behaviors.setup[Unit] { ctx =>
+          val pool = Routers.pool(poolSize = 4) {
             // make sure the workers are restarted if they fail
-          Behaviors.supervise(Worker()).onFailure[Exception](SupervisorStrategy.restart))
+            Behaviors.supervise(Worker()).onFailure[Exception](SupervisorStrategy.restart)
+          }
           val router = ctx.spawn(pool, "worker-pool")
 
           (0 to 10).foreach { n =>
@@ -81,9 +86,12 @@ class RouterSpec extends ScalaTestWithActorTestKit("akka.loglevel=warning") with
 
           val alternativeRouter = ctx.spawn(alternativePool, "alternative-pool")
           alternativeRouter ! Worker.DoLog("msg")
-
+          //#pool
           Behaviors.empty
-      })
+
+        }
+        //#pool
+      )
 
       probe.receiveMessages(11)
     }
@@ -98,8 +106,9 @@ class RouterSpec extends ScalaTestWithActorTestKit("akka.loglevel=warning") with
         def DoLog(text: String) = RouterSpec.Worker.DoLog(text)
       }
 
-      spawn(Behaviors.setup[Unit] { ctx =>
+      spawn(
         // #group
+        Behaviors.setup[Unit] { ctx =>
           // this would likely happen elsewhere - if we create it locally we
           // can just as well use a pool
           val worker = ctx.spawn(Worker(), "worker")
@@ -113,10 +122,11 @@ class RouterSpec extends ScalaTestWithActorTestKit("akka.loglevel=warning") with
           (0 to 10).foreach { n =>
             router ! Worker.DoLog(s"msg $n")
           }
-        // #group
 
           Behaviors.empty
-      })
+        }
+        // #group
+      )
 
       probe.receiveMessages(10)
     }

akka-docs/src/main/paradox/typed/routers.md

@@ -34,6 +34,16 @@ To make a resilient router that deals with failures the routee `Behavior` must b
 
 As actor children are always local the routees are never spread across a cluster with a pool router.
 
+Let's first introduce the routee:
+
+Scala
+:  @@snip [RouterSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/RouterSpec.scala) { #routee }
+
+Java
+:  @@snip [RouterTest.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/RouterTest.java) { #routee }
+
+After having defined the routee, we can now concentrate on configuring the router itself. Note again the the router is an Actor in itself:
+
 Scala
 :  @@snip [RouterSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/RouterSpec.scala) { #pool }
 
@@ -74,7 +84,6 @@ Scala
 Java
 :  @@snip [RouterTest.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/RouterTest.java) { #group }
 
-
 ## Routing strategies
 
 There are three different strategies for selecting which routee a message is forwarded to that can be selected
@@ -98,7 +107,6 @@ This is the default for pool routers as the pool of routees is expected to remai
 
 An optional parameter `preferLocalRoutees` can be used for this strategy. Routers will only use routees located in local actor system if `preferLocalRoutees` is true and local routees do exist. The default value for this parameter is false.
 
-
 ### Random
 
 Randomly selects a routee when a message is sent through the router.