Adding documentation for ask timeout expiry

akka-actor/src/main/scala/akka/actor/ActorRef.scala

@@ -106,6 +106,8 @@ abstract class ActorRef extends java.lang.Comparable[ActorRef] with Serializable
    * Akka Java API.
    *
    * Sends a message asynchronously returns a future holding the eventual reply message.
+   * The Future will be completed with an [[akka.actor.AskTimeoutException]] after the given
+   * timeout has expired.
    *
    * <b>NOTE:</b>
    * Use this method with care. In most cases it is better to use 'tell' together with the sender
@@ -177,6 +179,9 @@ trait ScalaActorRef { ref: ActorRef ⇒
 
   /**
    * Sends a message asynchronously, returning a future which may eventually hold the reply.
+   * The Future will be completed with an [[akka.actor.AskTimeoutException]] after the given
+   * timeout has expired.
+   *
    * <b>NOTE:</b>
    * Use this method with care. In most cases it is better to use '!' together with implicit or explicit
    * sender parameter to implement non-blocking request/response message exchanges.

akka-docs/java/untyped-actors.rst

@@ -280,8 +280,9 @@ If invoked without the sender parameter the sender will be
 Ask: Send-And-Receive-Future
 ----------------------------
 
-Using ``ask`` will send a message to the receiving Actor asynchronously and
+Using ``?`` will send a message to the receiving Actor asynchronously and
-will immediately return a :class:`Future`:
+will immediately return a :class:`Future` which will be completed with
+an ``akka.actor.AskTimeoutException`` after the specified timeout:
 
 .. code-block:: java
 

akka-docs/scala/actors.rst

@@ -318,7 +318,8 @@ Ask: Send-And-Receive-Future
 ----------------------------
 
 Using ``?`` will send a message to the receiving Actor asynchronously and
-will immediately return a :class:`Future`:
+will immediately return a :class:`Future` which will be completed with
+an ``akka.actor.AskTimeoutException`` after the specified timeout:
 
 .. code-block:: scala