Changed 'return' to 'raise gen.Return()' to fix Issue #1292, explanation added.

diff --git a/docs/guide/async.rst b/docs/guide/async.rst
index 8d5f27c6acc47bb9eb896a653d5464f5ba88d478..67b702dac08f6a1a4ba1b612265076c4d1753ef4 100644 (file)
--- a/docs/guide/async.rst
+++ b/docs/guide/async.rst
@@ -108,4 +108,6 @@ the original synchronous version::
     def fetch_coroutine(url):
         http_client = AsyncHTTPClient()
         response = yield http_client.fetch(url)
-        return response.body
+        raise gen.Return(response.body)
+
+The statement ``raise gen.Return(response.body)`` is an artifact of Python 2, in which generators aren't allowed to return values. To overcome this, Tornado coroutines raise a special kind of exception called a ``Return``. The coroutine catches this exception and treats it like a returned value. In Python 3, a ``return response.body`` achieves the same result.