mention interoperability in doc

actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/DispatchersDocTest.java

@@ -29,4 +29,26 @@ public static void spawnDispatchers(ActorContext<Integer> context, Behavior<Stri
         behavior, "DispatcherFromConfig", DispatcherSelector.fromConfig("your-dispatcher"));
     // #spawn-dispatcher
   }
+
+  public static void spawnDispatchersWithInteroperability(
+      ActorContext<Integer> context, Behavior<String> behavior) {
+    // #interoperability-with-mailbox
+    context.spawn(
+        behavior,
+        "ExplicitDefaultDispatcher",
+        DispatcherSelector.defaultDispatcher().withMailboxFromConfig("your-mailbox"));
+    context.spawn(
+        behavior,
+        "BlockingDispatcher",
+        DispatcherSelector.blocking().withMailboxFromConfig("your-mailbox"));
+    context.spawn(
+        behavior,
+        "ParentDispatcher",
+        DispatcherSelector.sameAsParent().withMailboxFromConfig("your-mailbox"));
+    context.spawn(
+        behavior,
+        "DispatcherFromConfig",
+        DispatcherSelector.fromConfig("your-dispatcher").withMailboxFromConfig("your-mailbox"));
+    // #interoperability-with-mailbox
+  }
 }

actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/MailboxDocTest.java

@@ -59,4 +59,33 @@ public void startSomeActorsWithDifferentMailboxes() {
     ActorRef<Void> ref = testKit.spawn(setup);
     testProbe.receiveMessage();
   }
+
+  @Test
+  public void startSomeActorsWithMailboxSelectorInteroperability() {
+    TestProbe<Done> testProbe = testKit.createTestProbe();
+    Behavior<String> childBehavior = Behaviors.empty();
+
+    Behavior<Void> setup =
+        Behaviors.setup(
+            context -> {
+              // #interoperability-with-dispatcher
+              context.spawn(
+                  childBehavior,
+                  "bounded-mailbox-child",
+                  MailboxSelector.bounded(100).withDispatcherDefault());
+
+              context.spawn(
+                  childBehavior,
+                  "from-config-mailbox-child",
+                  MailboxSelector.fromConfig("my-app.my-special-mailbox")
+                      .withMailboxFromConfig("custom-dispatcher"));
+              // #interoperability-with-dispatcher
+
+              testProbe.ref().tell(Done.getInstance());
+              return Behaviors.stopped();
+            });
+
+    ActorRef<Void> ref = testKit.spawn(setup);
+    testProbe.receiveMessage();
+  }
 }

actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/DispatchersDocSpec.scala

@@ -65,6 +65,24 @@ object DispatchersDocSpec {
     Behaviors.same
   }
 
+  val interoperableExample = Behaviors.receive[Any] { (context, _) =>
+    // #interoperability-with-mailbox
+    import org.apache.pekko.actor.typed.DispatcherSelector
+
+    context.spawn(yourBehavior, "DefaultDispatcher")
+    context.spawn(yourBehavior, "ExplicitDefaultDispatcher",
+      DispatcherSelector.default().withMailboxFromConfig("your-mailbox"))
+    context.spawn(yourBehavior, "BlockingDispatcher",
+      DispatcherSelector.blocking().withMailboxFromConfig("your-mailbox"))
+    context.spawn(yourBehavior, "ParentDispatcher",
+      DispatcherSelector.sameAsParent().withMailboxFromConfig("your-mailbox"))
+    context.spawn(yourBehavior, "DispatcherFromConfig",
+      DispatcherSelector.fromConfig("your-dispatcher").withMailboxFromConfig("your-mailbox"))
+    // #interoperability-with-mailbox
+
+    Behaviors.same
+  }
+
 }
 
 class DispatchersDocSpec

actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/MailboxDocSpec.scala

@@ -47,6 +47,28 @@ class MailboxDocSpec
 
       probe.receiveMessage()
     }
+
+    "interoperability with DispatcherSelector" in {
+
+      val probe = createTestProbe[Done]()
+      val childBehavior: Behavior[String] = Behaviors.empty
+      val parent: Behavior[Unit] = Behaviors.setup { context =>
+        // #interoperability-with-dispatcher
+        context.spawn(childBehavior, "bounded-mailbox-child", MailboxSelector.bounded(100).withDispatcherDefault)
+
+        val props =
+          MailboxSelector.fromConfig("my-app.my-special-mailbox").withDispatcherFromConfig("custom-dispatcher")
+        context.spawn(childBehavior, "from-config-mailbox-child", props)
+        // #interoperability-with-dispatcher
+
+        probe.ref ! Done
+        Behaviors.stopped
+      }
+      spawn(parent)
+
+      probe.receiveMessage()
+
+    }
   }
 
 }

docs/src/main/paradox/typed/dispatchers.md

@@ -55,7 +55,7 @@ A default dispatcher is used for all actors that are spawned without specifying
 This is suitable for all actors that don't block. Blocking in actors needs to be carefully managed, more
 details @ref:[here](#blocking-needs-careful-management).
 
-To select a dispatcher use `DispatcherSelector` to create a `Props` instance for spawning your actor:
+To select a dispatcher use @apidoc[DispatcherSelector](DispatcherSelector$)  to create a @apidoc[Props](typed.Props) instance for spawning your actor:
 
 Scala
 :  @@snip [DispatcherDocSpec.scala](/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/DispatchersDocSpec.scala) { #spawn-dispatcher }
@@ -74,6 +74,17 @@ The final example shows how to load a custom dispatcher from configuration and r
 <!-- Same between Java and Scala -->
 @@snip [DispatcherDocSpec.scala](/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/DispatchersDocSpec.scala) { #config }
 
+### Interoperability with MailboxSelector
+
+The @apidoc[DispatcherSelector](DispatcherSelector$) will create a @apidoc[Props](typed.Props) instance that can be both set up Dispatcher and Mailbox, 
+which means that you can continue to set up Mailbox through chain calls.
+
+Scala
+:  @@snip [DispatcherDocSpec.scala](/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/DispatchersDocSpec.scala) { #interoperability-with-mailbox }
+
+Java
+:  @@snip [DispatcherDocTest.java](/actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/DispatchersDocTest.java) { #interoperability-with-mailbox }
+
 ## Types of dispatchers
 
 There are 2 different types of message dispatchers:

docs/src/main/paradox/typed/mailboxes.md

@@ -58,6 +58,17 @@ configuration section from the @apidoc[ActorSystem](typed.ActorSystem) configura
 `id` key with the configuration path of the mailbox type and adding a
 fall-back to the default mailbox configuration section.
 
+### Interoperability with DispatcherSelector
+
+The @apidoc[MailboxSelector](MailboxSelector$) will create a @apidoc[Props](typed.Props) instance that can be both set up Dispatcher and Mailbox,
+which means that you can continue to set up Dispatcher through chain calls.
+
+Scala
+:  @@snip [MailboxDocSpec.scala](/actor-typed-tests/src/test/scala/docs/org/apache/pekko/typed/MailboxDocSpec.scala) { #interoperability-with-dispatcher }
+
+Java
+:  @@snip [MailboxDocTest.java](/actor-typed-tests/src/test/java/jdocs/org/apache/pekko/typed/MailboxDocTest.java) { #interoperability-with-dispatcher }
+
 ## Mailbox Implementations
 
 Pekko ships with a number of mailbox implementations: