gen: Doc touchups

docs/gen.rst

@@ -34,17 +34,6 @@
 
    .. autofunction:: multi_future
 
-   .. autofunction:: Task
-
-   .. class:: Arguments
-
-      The result of a `Task` or `Wait` whose callback had more than one
-      argument (or keyword arguments).
-
-      The `Arguments` object is a `collections.namedtuple` and can be
-      used either as a tuple ``(args, kwargs)`` or an object with attributes
-      ``args`` and ``kwargs``.
-
    .. autofunction:: convert_yielded
 
    .. autofunction:: maybe_future
@@ -70,3 +59,18 @@
    .. autoclass:: WaitAll
 
    .. autoclass:: MultiYieldPoint
+
+   .. autofunction:: Task
+
+   .. class:: Arguments
+
+      The result of a `Task` or `Wait` whose callback had more than one
+      argument (or keyword arguments).
+
+      The `Arguments` object is a `collections.namedtuple` and can be
+      used either as a tuple ``(args, kwargs)`` or an object with attributes
+      ``args`` and ``kwargs``.
+
+      .. deprecated:: 5.1
+
+         This class will be removed in 6.0.

tornado/gen.py

@@ -261,9 +261,6 @@ def coroutine(func):
     ``callback`` argument is not visible inside the decorated
     function; it is handled by the decorator itself.
 
-    From the caller's perspective, ``@gen.coroutine`` is similar to
-    the combination of ``@return_future`` and ``@gen.engine``.
-
     .. warning::
 
        When exceptions occur inside a coroutine, the exception