playframework/playframework — pull request #2187 by fernandoacorreia (2013-12-23 19:10:13+00:00)
Title: Clarify documentation on Action asynchronicity

When someone is learning about the Play framework, it takes some time to realize that Action { } and Action.async { } are both asynchronous.

In the Main concepts topic, [HTTP programming](http://www.playframework.com/documentation/2.2.x/ScalaActions) talks about Actions, without mentioning asynchronicity. [Asynchronous HTTP programming](http://www.playframework.com/documentation/2.2.x/ScalaAsync) discusses Action.async without mentioning that regular Action is also async. In fact, the text under "Why asynchronous results?" leads newcomers to the impression that in order to an action to be asynchronous you need to explicitly create a Future[Result] and return it with Action.async.

The [async by default forum thread](https://groups.google.com/d/msg/play-framework-dev/30MqnKDp0Fs/25PU-Y0RhGoJ) explains clearly how things actually work, but it's not easily discoverable.

the [Should you always use Action.async? forum thread](https://groups.google.com/forum/#!topic/play-framework/WWQ0HeLDOjg) adds additional information and serves as an example of the common misunderstandings.

I propose that someone knowledgeable of Play's internals add some clarification about this, possibly in the [Handling asynchronous results documentation page](http://www.playframework.com/documentation/2.2.x/ScalaAsync), explaining that Actions are async by default. Some additional information or links to related concepts such as common patters for using thread pools, Actors, etc., as explained in the forum threads above, would also be great.