# HG changeset patch
# Parent 256d5c7146cb968e9d6e200c99b0a1ec9e2faf14

diff -r 256d5c7146cb Doc/library/types.rst
--- a/Doc/library/types.rst	Wed Jul 29 12:55:33 2015 +1200
+++ b/Doc/library/types.rst	Sat Aug 01 08:17:38 2015 +0000
@@ -284,20 +284,27 @@
 Coroutine Utility Functions
 ---------------------------
 
-.. function:: coroutine(gen_func)
+.. decorator:: coroutine
 
-   This function transforms a :term:`generator` function into a
+   This :term:`decorator` transforms a :term:`generator` function into a
    :term:`coroutine function` which returns a generator-based coroutine.
-   The generator-based coroutine is still a :term:`generator iterator`,
+
+   If the decorated function is a generator function and is not already a
+   coroutine function, it will be modified in-place.  The object returned
+   by the modified function is still a :term:`generator iterator`,
    but is also considered to be a :term:`coroutine` object and is
    :term:`awaitable`.  However, it may not necessarily implement
    the :meth:`__await__` method.
 
-   If *gen_func* is a generator function, it will be modified in-place.
+   If the decorated function is already a coroutine function, including
+   a generator-based function that has already been modified, it is
+   returned as is.
 
-   If *gen_func* is not a generator function, it will be wrapped. If it
-   returns an instance of :class:`collections.abc.Generator`, the instance
-   will be wrapped in an *awaitable* proxy object.  All other types
+   If the decorated function is neither a generator function nor a coroutine
+   function, it will be wrapped, and its return value will be inspected.
+   If it returns an instance of :class:`collections.abc.Generator` that
+   is not also an instance of :class:`collections.abc.Coroutine`, the
+   instance will be wrapped in a coroutine proxy object.  All other types
    of objects will be returned as is.
 
    .. versionadded:: 3.5