From: Ben Darnell <ben@bendarnell.com>
Date: Thu, 18 Apr 2013 14:40:20 +0000 (-0400)
Subject: Expand docs for @asynchronous decorator and other cleanups.
X-Git-Tag: v3.1.0~103
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e4bba5ce216daca80bc9bb151a18f4220fe26c78;p=thirdparty%2Ftornado.git

Expand docs for @asynchronous decorator and other cleanups.

Closes #742.
---

diff --git a/docs/web.rst b/docs/web.rst
index 041152c23..cfc9d480d 100644
--- 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 64287c531..938fef61b 100644
--- 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 1432723a9..51663a4a9 100644
--- 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 cb1af173b..6abf42c09 100644
--- 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