diff --git a/akka-docs/src/main/paradox/mailboxes.md b/akka-docs/src/main/paradox/mailboxes.md
index bec7d9335f..a36fd4e3e6 100644
--- a/akka-docs/src/main/paradox/mailboxes.md
+++ b/akka-docs/src/main/paradox/mailboxes.md
@@ -18,8 +18,8 @@ To use Mailboxes, you must add the following dependency in your project:
 
 ## Introduction
 
-An Akka `Mailbox` holds the messages that are destined for an `Actor`.
-Normally each `Actor` has its own mailbox, but with for example a `BalancingPool`
+An Akka `Mailbox` holds the messages that are destined for an @apidoc[akka.actor.Actor].
+Normally each `Actor` has its own mailbox, but with for example a @apidoc[BalancingPool]
 all routees will share a single mailbox instance.
 
 For more details on advanced mailbox config and custom mailbox implementations, see @ref[Mailboxes](typed/mailboxes.md#mailbox-implementations).
@@ -30,9 +30,9 @@ For more details on advanced mailbox config and custom mailbox implementations,
 
 The default mailbox is used when the mailbox is not specified.
 This is an unbounded mailbox, backed by a
-`java.util.concurrent.ConcurrentLinkedQueue`.
+@javadoc[java.util.concurrent.ConcurrentLinkedQueue](java.util.concurrent.ConcurrentLinkedQueue).
 
-`SingleConsumerOnlyUnboundedMailbox` is an even more efficient mailbox, and
+@apidoc[SingleConsumerOnlyUnboundedMailbox] is an even more efficient mailbox, and
 it can be used as the default mailbox, but it cannot be used with a BalancingDispatcher.
 
 Configuration of `SingleConsumerOnlyUnboundedMailbox` as default mailbox:
@@ -46,7 +46,7 @@ akka.actor.default-mailbox {
 ### Requiring a Message Queue Type for an Actor
 
 It is possible to require a certain type of message queue for a certain type of actor
-by having that actor @scala[extend]@java[implement] the parameterized @scala[trait]@java[interface] `RequiresMessageQueue`. Here is
+by having that actor @scala[extend]@java[implement] the parameterized @scala[trait]@java[interface] @apidoc[RequiresMessageQueue]. Here is
 an example:
 
 Scala
@@ -74,7 +74,7 @@ The type of the queue in the mailbox created for an actor will be checked agains
 ### Requiring a Message Queue Type for a Dispatcher
 
 A dispatcher may also have a requirement for the mailbox type used by the
-actors running on it. An example is the @apidoc[BalancingDispatcher] which requires a
+actors running on it. An example is the `BalancingDispatcher` which requires a
 message queue that is thread-safe for multiple concurrent consumers. Such a
 requirement is formulated within the dispatcher configuration section:
 
@@ -91,12 +91,12 @@ requirement—then actor creation will fail.
 
 ### How the Mailbox Type is Selected
 
-When an actor is created, the `ActorRefProvider` first determines the
+When an actor is created, the @apidoc[ActorRefProvider] first determines the
 dispatcher which will execute it. Then the mailbox is determined as follows:
 
  1. If the actor's deployment configuration section contains a `mailbox` key,
 this refers to a configuration section describing the mailbox type.
- 2. If the actor's `Props` contains a mailbox selection then that names a configuration section describing the
+ 2. If the actor's @apidoc[Props](akka.actor.Props) contains a mailbox selection then that names a configuration section describing the
 mailbox type to be used. This needs to be an absolute config path,
 for example `myapp.special-mailbox`, and is not nested inside the `akka` namespace.
  3. If the dispatcher's configuration section contains a `mailbox-type` key
@@ -166,7 +166,7 @@ It can be configured like this:
 
 @@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #control-aware-mailbox-config }
 
-Control messages need to extend the `ControlMessage` trait:
+Control messages need to extend the @apidoc[akka.dispatch.ControlMessage] @scala[trait]@java[interface]:
 
 Scala
 :   @@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #control-aware-mailbox-messages }
@@ -184,13 +184,13 @@ Java
 
 ## Special Semantics of `system.actorOf`
 
-In order to make `system.actorOf` both synchronous and non-blocking while
-keeping the return type `ActorRef` (and the semantics that the returned
+In order to make @apidoc[system.actorOf](akka.actor.ActorRefFactory) {scala="#actorOf(props:akka.actor.Props):akka.actor.ActorRef" java="#actorOf(akka.actor.Props)"} both synchronous and non-blocking while
+keeping the return type @apidoc[akka.actor.ActorRef] (and the semantics that the returned
 ref is fully functional), special handling takes place for this case. Behind
 the scenes, a hollow kind of actor reference is constructed, which is sent to
 the system’s guardian actor who actually creates the actor and its context and
 puts those inside the reference. Until that has happened, messages sent to the
-`ActorRef` will be queued locally, and only upon swapping the real
+@apidoc[akka.actor.ActorRef] will be queued locally, and only upon swapping the real
 filling in will they be transferred into the real mailbox. Thus,
 
 Scala
@@ -214,4 +214,4 @@ Java
     @@@
 
 will probably fail; you will have to allow for some time to pass and retry the
-check à la `TestKit.awaitCond`.
+check à la @scala[@scaladoc[TestKit.awaitCond](akka.testkit.TestKit#awaitCond(p:=%3EBoolean,max:scala.concurrent.duration.Duration,interval:scala.concurrent.duration.Duration,message:String):Unit)]@java[@javadoc[TestKit.awaitCond](akka.testkit.javadsl.TestKit#awaitCond(java.time.Duration,java.time.Duration,java.lang.String,java.util.function.Supplier))].