Issue #22112, asyncio doc: replace loop.create_task(coro) with

asyncio.async(coro), mention that asyncio.async() can be used to scheduler a
coroutine, and make it clear that create_task() is only available in Python
3.4.2 and later.

3 files changed, 19 insertions, 16 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 1e16b9e..ff685bb 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -147,9 +147,8 @@ Coroutines
    interoperability. In this case, the result type is a subclass of
    :class:`Task`.
 
-   .. seealso::
-
-      The :meth:`async` function.
+   This method was added in Python 3.4.2. Use the :func:`async` function to
+   support also older Python versions.
 
    .. versionadded:: 3.4.2
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 81bd7f0..11d13c8 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -43,7 +43,7 @@ Stream functions
    :class:`StreamWriter` object.  The *client_connected_cb* parameter can
    either be a plain callback function or a :ref:`coroutine function
    <coroutine>`; if it is a coroutine function, it will be automatically
-   wrapped in a future using the :meth:`BaseEventLoop.create_task` method.
+   converted into a :class:`Task`.
 
    The rest of the arguments are all the usual arguments to
    :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index db688f5..cde0e34 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -52,7 +52,9 @@ generator object, which doesn't do anything until you iterate over it.
 In the case of a coroutine object, there are two basic ways to start
 it running: call ``yield from coroutine`` from another coroutine
 (assuming the other coroutine is already running!), or schedule its execution
-using the :meth:`BaseEventLoop.create_task` method.
+using the :func:`async` function or the :meth:`BaseEventLoop.create_task`
+method.
+
 
 Coroutines (and tasks) can only run when the event loop is running.
 
@@ -256,7 +258,7 @@ Example combining a :class:`Future` and a :ref:`coroutine function
 
     loop = asyncio.get_event_loop()
     future = asyncio.Future()
-    loop.create_task(slow_operation(future))
+    asyncio.async(slow_operation(future))
     loop.run_until_complete(future)
     print(future.result())
     loop.close()
@@ -292,7 +294,7 @@ flow::
 
     loop = asyncio.get_event_loop()
     future = asyncio.Future()
-    loop.create_task(slow_operation(future))
+    asyncio.async(slow_operation(future))
     future.add_done_callback(got_result)
     try:
         loop.run_forever()
@@ -339,8 +341,8 @@ Task
    <coroutine>` did not complete. It is probably a bug and a warning is
    logged: see :ref:`Pending task destroyed <asyncio-pending-task-destroyed>`.
 
-   Don't create directly :class:`Task` instances: use the
-   :meth:`BaseEventLoop.create_task` method.
+   Don't create directly :class:`Task` instances: use the :func:`async`
+   function or the :meth:`BaseEventLoop.create_task` method.
 
    .. classmethod:: all_tasks(loop=None)
 
@@ -424,9 +426,9 @@ Example executing 3 tasks (A, B, C) in parallel::
 
     loop = asyncio.get_event_loop()
     tasks = [
-        loop.create_task(factorial("A", 2)),
-        loop.create_task(factorial("B", 3)),
-        loop.create_task(factorial("C", 4))]
+        asyncio.async(factorial("A", 2)),
+        asyncio.async(factorial("B", 3)),
+        asyncio.async(factorial("C", 4))]
     loop.run_until_complete(asyncio.wait(tasks))
     loop.close()
 
@@ -475,11 +477,14 @@ Task functions
 
 .. function:: async(coro_or_future, \*, loop=None)
 
-   Wrap a :ref:`coroutine object <coroutine>` in a future using the
-   :meth:`BaseEventLoop.create_task` method.
+   Wrap a :ref:`coroutine object <coroutine>` in a future.
 
    If the argument is a :class:`Future`, it is returned directly.
 
+   .. seealso::
+
+      The :meth:`BaseEventLoop.create_task` method.
+
 .. function:: gather(\*coros_or_futures, loop=None, return_exceptions=False)
 
    Return a future aggregating results from the given coroutine objects or
@@ -595,8 +600,7 @@ Task functions
    to complete with timeout. If *timeout* is ``None``, block until the future
    completes.
 
-   Coroutine objects are wrapped in a future using the
-   :meth:`BaseEventLoop.create_task` method.
+   Coroutine will be wrapped in :class:`Task`.
 
    Returns result of the Future or coroutine.  When a timeout occurs, it
    cancels the task and raises :exc:`asyncio.TimeoutError`. To avoid the task