Expand docs for @asynchronous decorator and other cleanups.

Closes #742.

diff --git a/docs/web.rst b/docs/web.rst
index 041152c23c7a4a9d78722041bfce0ebd8542b27b..cfc9d480dc8cf9e93f8a5d35195293e46d4c3680 100644 (file)
--- a/docs/web.rst
+++ b/docs/web.rst
@@ -14,8 +14,10 @@
    .. automethod:: RequestHandler.prepare
    .. automethod:: RequestHandler.on_finish
 
-   Implement any of the following methods to handle the corresponding
-   HTTP method.
+   .. _verbs:
+
+   Implement any of the following methods (collectively known as the
+   HTTP verb methods) to handle the corresponding HTTP method.
 
    .. automethod:: RequestHandler.get
    .. automethod:: RequestHandler.post
@@ -38,10 +40,11 @@
    .. attribute:: RequestHandler.path_args
    .. attribute:: RequestHandler.path_kwargs
 
-      The ``path_args`` and ``path_kwargs`` attributes contain the positional
-      and keyword arguments that are passed to the `get`/`post`/etc methods.
-      These attributes are set before those methods are called, so the values
-      are available during `prepare`.
+      The ``path_args`` and ``path_kwargs`` attributes contain the
+      positional and keyword arguments that are passed to the
+      :ref:`HTTP verb methods <verbs>`.  These attributes are set
+      before those methods are called, so the values are available
+      during `prepare`.
 
    Output
    ^^^^^^

diff --git a/tornado/gen.py b/tornado/gen.py
index 64287c53155736da7121c6f005c163aabbc6ae9e..938fef61b4d7a59725c45f7bf7adb7ce15f50a9f 100644 (file)
--- a/tornado/gen.py
+++ b/tornado/gen.py
@@ -121,7 +121,7 @@ def engine(func):
     In most cases, functions decorated with `engine` should take
     a ``callback`` argument and invoke it with their result when
     they are finished.  One notable exception is the
-    `~tornado.web.RequestHandler` ``get``/``post``/etc methods,
+    `~tornado.web.RequestHandler` :ref:`HTTP verb methods <verbs>`,
     which use ``self.finish()`` in place of a callback argument.
     """
     @functools.wraps(func)
@@ -166,7 +166,7 @@ def coroutine(func):
     Any generator that yields objects from this module must be wrapped
     in either this decorator or `engine`.  These decorators only work
     on functions that are already asynchronous.  For
-    `~tornado.web.RequestHandler` ``get``/``post``/etc methods, this
+    `~tornado.web.RequestHandler` :ref:`HTTP verb methods <verbs>` methods, this
     means that both the `tornado.web.asynchronous` and
     `tornado.gen.coroutine` decorators must be used (for proper
     exception handling, ``asynchronous`` should come before

diff --git a/tornado/testing.py b/tornado/testing.py
index 1432723a91cf60425b59affcdbddabc8ba28d268..51663a4a97afcbf4898c92612a219958c5edfc04 100644 (file)
--- a/tornado/testing.py
+++ b/tornado/testing.py
@@ -386,7 +386,7 @@ def gen_test(func=None, timeout=None):
 
     By default, ``@gen_test`` times out after 5 seconds. The timeout may be
     overridden globally with the ASYNC_TEST_TIMEOUT environment variable,
-    or for each test with the ``timeout`` keyword argument:
+    or for each test with the ``timeout`` keyword argument::
 
         class MyTest(AsyncHTTPTestCase):
             @gen_test(timeout=10)

diff --git a/tornado/web.py b/tornado/web.py
index cb1af173bbe346fb270d6b2cc454ab92157171f8..6abf42c09f8fd3a77d976c4441eb1c1318181062 100644 (file)
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -194,7 +194,7 @@ class RequestHandler(object):
         raise HTTPError(405)
 
     def prepare(self):
-        """Called at the beginning of a request before `get`/`post`/etc.
+        """Called at the beginning of a request before  `get`/`post`/etc.
 
         Override this method to perform common initialization regardless
         of the request method.
@@ -1152,6 +1152,13 @@ class RequestHandler(object):
 def asynchronous(method):
     """Wrap request handler methods with this if they are asynchronous.
 
+    This decorator should only be applied to the :ref:`HTTP verb
+    methods <verbs>`; its behavior is undefined for any other method.
+    This decorator does not *make* a method asynchronous; it tells
+    the framework that the method *is* asynchronous.  For this decorator
+    to be useful the method must (at least sometimes) do something
+    asynchronous.
+
     If this decorator is given, the response is not finished when the
     method returns. It is up to the request handler to call
     `self.finish() <RequestHandler.finish>` to finish the HTTP