Expand docs for @asynchronous decorator and other cleanups.

Closes #742.

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
    ^^^^^^

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

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)

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