diff --git a/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/StashBuffer.scala b/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/StashBuffer.scala
index 2fafd4ea33..2f01bff281 100644
--- a/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/StashBuffer.scala
+++ b/akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/StashBuffer.scala
@@ -102,10 +102,10 @@ import java.util.function.{ Predicate, Function => JFunction }
   def clear(): Unit
 
   /**
-   * Process all stashed messages with the `behavior` and the returned
-   * [[Behavior]] from each processed message. The `StashBuffer` will be
-   * empty after processing all messages, unless an exception is thrown
-   * or messages are stashed while unstashing.
+   * Transition to the given `behavior` and process all stashed messages.
+   * Messages will be processed in the same order they arrived.
+   * The `StashBuffer` will be empty after processing all messages,
+   * unless an exception is thrown or messages are stashed while unstashing.
    *
    * If an exception is thrown by processing a message a proceeding messages
    * and the message causing the exception have been removed from the
@@ -120,8 +120,8 @@ import java.util.function.{ Predicate, Function => JFunction }
   def unstashAll(behavior: Behavior[T]): Behavior[T]
 
   /**
-   * Process `numberOfMessages` of the stashed messages with the `behavior`
-   * and the returned [[Behavior]] from each processed message.
+   * Transition to the given `behavior` and process `numberOfMessages` of the stashed messages.
+   * The messages will be processed in the same order they arrived.
    *
    * The purpose of this method, compared to `unstashAll`, is to unstash a limited
    * number of messages and then send a message to `self` before continuing unstashing
diff --git a/akka-actor-typed/src/main/scala/akka/actor/typed/scaladsl/StashBuffer.scala b/akka-actor-typed/src/main/scala/akka/actor/typed/scaladsl/StashBuffer.scala
index f04a83135f..f2ba822054 100644
--- a/akka-actor-typed/src/main/scala/akka/actor/typed/scaladsl/StashBuffer.scala
+++ b/akka-actor-typed/src/main/scala/akka/actor/typed/scaladsl/StashBuffer.scala
@@ -114,10 +114,10 @@ import akka.annotation.{ DoNotInherit, InternalApi }
   def clear(): Unit
 
   /**
-   * Process all stashed messages with the `behavior` and the returned
-   * [[Behavior]] from each processed message. The `StashBuffer` will be
-   * empty after processing all messages, unless an exception is thrown
-   * or messages are stashed while unstashing.
+   * Transition to the given `behavior` and process all stashed messages.
+   * Messages will be processed in the same order they arrived.
+   * The `StashBuffer` will be empty after processing all messages,
+   * unless an exception is thrown or messages are stashed while unstashing.
    *
    * If an exception is thrown by processing a message a proceeding messages
    * and the message causing the exception have been removed from the
@@ -127,13 +127,13 @@ import akka.annotation.{ DoNotInherit, InternalApi }
    * messages will not be processed by this call and have to be unstashed
    * in another call.
    *
-   * The initial `behavior` passed to `unstashAll` must not be `unhandled`.
+   * The `behavior` passed to `unstashAll` must not be `unhandled`.
    */
   def unstashAll(behavior: Behavior[T]): Behavior[T]
 
   /**
-   * Process `numberOfMessages` of the stashed messages with the `behavior`
-   * and the returned [[Behavior]] from each processed message.
+   * Transition to the given `behavior` and process `numberOfMessages` of the stashed messages.
+   * The messages will be processed in the same order they arrived.
    *
    * The purpose of this method, compared to `unstashAll` is to unstash a limited
    * number of messages and then send a message to `self` before continuing unstashing