Non symbolic ask

akka-actor-typed/src/main/scala/akka/actor/typed/scaladsl/AskPattern.scala

@@ -21,17 +21,47 @@ import akka.actor.typed.internal.InternalRecipientRef
  * The ask-pattern implements the initiator side of a request–reply protocol.
  * The `?` operator is pronounced as "ask".
  *
- * See [[AskPattern.Askable.?]] for details
+ * See [[AskPattern.Askable.ask]] for details
  */
 object AskPattern {
 
   /**
-   * See [[?]]
+   * See [[ask]]
    */
   implicit final class Askable[T](val ref: RecipientRef[T]) extends AnyVal {
     /**
      * The ask-pattern implements the initiator side of a request–reply protocol.
-     * The `?` operator is pronounced as "ask".
+     * The `?` operator is pronounced as "ask" (and a convenience symbolic operation
+     * kept since the previous ask API, if unsure which one to use, prefer the non-symbolic
+     * method as it leads to fewer surprises with the scope of the `replyTo` function)
+     *
+     * Note that if you are inside of an actor you should prefer [[ActorContext.ask]]
+     * as that provides better safety.
+     *
+     * The party that asks may be within or without an Actor, since the
+     * implementation will fabricate a (hidden) [[ActorRef]] that is bound to a
+     * [[scala.concurrent.Promise]]. This ActorRef will need to be injected in the
+     * message that is sent to the target Actor in order to function as a reply-to
+     * address, therefore the argument to the ask / `?`
+     * operator is not the message itself but a function that given the reply-to
+     * address will create the message.
+     *
+     * {{{
+     * case class Request(msg: String, replyTo: ActorRef[Reply])
+     * case class Reply(msg: String)
+     *
+     * implicit val scheduler = system.scheduler
+     * implicit val timeout = Timeout(3.seconds)
+     * val target: ActorRef[Request] = ...
+     * val f: Future[Reply] = target ? (replyTo => (Request("hello", replyTo)))
+     * }}}
+     */
+    def ?[U](replyTo: ActorRef[U] ⇒ T)(implicit timeout: Timeout, @unused scheduler: Scheduler): Future[U] = {
+      ask(replyTo)(timeout, scheduler)
+    }
+
+    /**
+     * The ask-pattern implements the initiator side of a request–reply protocol.
      *
      * Note that if you are inside of an actor you should prefer [[ActorContext.ask]]
      * as that provides better safety.
@@ -54,7 +84,7 @@ object AskPattern {
      * val f: Future[Reply] = target ? replyTo => (Request("hello", replyTo))
      * }}}
      */
-    def ?[U](replyTo: ActorRef[U] ⇒ T)(implicit timeout: Timeout, @unused scheduler: Scheduler): Future[U] = {
+    def ask[U](replyTo: ActorRef[U] ⇒ T)(implicit timeout: Timeout, @unused scheduler: Scheduler): Future[U] = {
       // We do not currently use the implicit scheduler, but want to require it
       // because it might be needed when we move to a 'native' typed runtime, see #24219
       ref match {