Minor corrections from review comments

akka-docs/java/futures.rst

@@ -11,7 +11,6 @@ Introduction
 ------------
 
 In Akka, a `Future <http://en.wikipedia.org/wiki/Futures_and_promises>`_ is a data structure used to retrieve the result of some concurrent operation. This operation is usually performed by an ``Actor`` or by the ``Dispatcher`` directly. This result can be accessed synchronously (blocking) or asynchronously (non-blocking).
-Asynchronous usage is strongly recommended.
 
 Use with Actors
 ---------------
@@ -23,7 +22,8 @@ Using the ``ActorRef``\'s ``ask`` method to send a message will return a Future.
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports1,ask-blocking
 
-This will cause the current thread to block and wait for the ``UntypedActor`` to 'complete' the ``Future`` with it's reply. Blocking is discouraged though as it can cause performance problem. Alternatives to blocking are discussed further within this documentation.
+This will cause the current thread to block and wait for the ``UntypedActor`` to 'complete' the ``Future`` with it's reply. Blocking is discouraged though as it can cause performance problem.
+The blocking operations are located in ``Await.result`` and ``Await.ready`` to make it easy to spot where blocking occurs. Alternatives to blocking are discussed further within this documentation.
 Also note that the ``Future`` returned by an ``UntypedActor`` is a ``Future<Object>`` since an ``UntypedActor`` is dynamic. That is why the cast to ``String`` is used in the above sample.
 
 Use Directly

akka-docs/scala/code/akka/docs/future/FutureDocSpec.scala

@@ -9,6 +9,7 @@ import akka.actor.Status.Failure
 import akka.dispatch.Future
 import akka.dispatch.Await
 import akka.util.duration._
+import akka.dispatch.Promise
 
 object FutureDocSpec {
 
@@ -95,9 +96,7 @@ class FutureDocSpec extends AkkaSpec {
     val f1 = Future {
       "Hello" + "World"
     }
-    val f2 = Future {
+    val f2 = Promise.successful(3)
-      3
-    }
     val f3 = f1 map { x ⇒
       f2 map { y ⇒
         x.length * y
@@ -112,9 +111,7 @@ class FutureDocSpec extends AkkaSpec {
     val f1 = Future {
       "Hello" + "World"
     }
-    val f2 = Future {
+    val f2 = Promise.successful(3)
-      3
-    }
     val f3 = f1 flatMap { x ⇒
       f2 map { y ⇒
         x.length * y
@@ -133,6 +130,9 @@ class FutureDocSpec extends AkkaSpec {
       c ← Future(a - 1) //  5 - 1 = 4
     } yield b * c //  6 * 4 = 24
 
+    // Note that the execution of futures a, b, and c
+    // are not done in parallel.
+
     val result = Await.result(f, 1 second)
     result must be(24)
     //#for-comprehension

akka-docs/scala/futures.rst

@@ -11,7 +11,6 @@ Introduction
 ------------
 
 In Akka, a `Future <http://en.wikipedia.org/wiki/Futures_and_promises>`_ is a data structure used to retrieve the result of some concurrent operation. This operation is usually performed by an ``Actor`` or by the ``Dispatcher`` directly. This result can be accessed synchronously (blocking) or asynchronously (non-blocking).
-Asynchronous usage is strongly recommended.
 
 Use with Actors
 ---------------
@@ -23,7 +22,8 @@ Using an ``Actor``\'s ``?`` method to send a message will return a Future. To wa
 .. includecode:: code/akka/docs/future/FutureDocSpec.scala
    :include: ask-blocking
 
-This will cause the current thread to block and wait for the ``Actor`` to 'complete' the ``Future`` with it's reply. Blocking is discouraged though as it can cause performance problem. Alternatives to blocking are discussed further within this documentation.
+This will cause the current thread to block and wait for the ``Actor`` to 'complete' the ``Future`` with it's reply. Blocking is discouraged though as it can cause performance problem.
+The blocking operations are located in ``Await.result`` and ``Await.ready`` to make it easy to spot where blocking occurs. Alternatives to blocking are discussed further within this documentation.
 Also note that the ``Future`` returned by an ``Actor`` is a ``Future[Any]`` since an ``Actor`` is dynamic. That is why the ``asInstanceOf`` is used in the above sample.
 When using non-blocking it is better to use the ``mapTo`` method to safely try to cast a ``Future`` to an expected type: