Polish doc as part of asyncio doc improvement (GH-9185)

diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index cb574c308ad1bd3a6a8af6ca188a2724afbd63c9..e4986ba5eb265763c901907b2eba8e2c4cd34c4e 100644 (file)
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -98,9 +98,11 @@ Concurrency and multithreading
 
 An event loop runs in a thread (typically the main thread) and executes
 all callbacks and tasks in its thread.  While a task is running in the
-event loop, no other task is running in the same thread. When a task
-executes an ``await`` expression, the task gets suspended and the
-event loop executes the next task.
+event loop, no other tasks may run in the same thread. When a task
+executes an ``await`` expression, the running task gets suspended, and the
+event loop executes the next task. Prior to suspending the task, the awaiting
+chain is checked, and if the chain ends with a future, the running task is
+not suspended.
 
 To schedule a callback from a different thread, the
 :meth:`loop.call_soon_threadsafe` method should be used. Example::
@@ -123,9 +125,9 @@ To schedule a coroutine object from a different thread, the
      future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
      result = future.result(timeout)  # Wait for the result with a timeout
 
-The :meth:`loop.run_in_executor` method can be used with a thread pool
-executor to execute a callback in different thread to not block the thread of
-the event loop.
+The :meth:`loop.run_in_executor` method can be used with a
+:class:`concurrent.futures.ThreadPoolExecutor` to execute a callback in
+different thread so as not to block the event loop's main thread.
 
 .. seealso::
 
@@ -183,9 +185,10 @@ Detect coroutine objects never scheduled
 ----------------------------------------
 
 When a coroutine function is called and its result is not passed to
-:func:`ensure_future` or to the :meth:`loop.create_task` method,
-the execution of the coroutine object will never be scheduled which is
-probably a bug.  :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
+:meth:`asyncio.create_task` the execution of the coroutine object will
+never be scheduled which is probably a bug. Using ``asyncio.create_task`` is
+preferred to the low level :func:`ensure_future` and :meth:`loop.create_task`
+methods. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
 to :ref:`log a warning <asyncio-logger>` to detect it.
 
 Example with the bug::
@@ -204,8 +207,9 @@ Output in debug mode::
       File "test.py", line 7, in <module>
         test()
 
-The fix is to call the :func:`ensure_future` function or the
-:meth:`loop.create_task` method with the coroutine object.
+The fix is to call the :meth:`asyncio.create_task` function. Using
+``asyncio.create_task`` is preferred to the low level :func:`ensure_future` and
+:meth:`loop.create_task` methods.
 
 .. seealso::
 
@@ -280,14 +284,9 @@ coroutine in another coroutine and use classic try/except::
     loop.run_forever()
     loop.close()
 
-Another option is to use the :meth:`loop.run_until_complete`
-function::
+Another option is to use the :meth:`asyncio.run` function::
 
-    task = asyncio.ensure_future(bug())
-    try:
-        loop.run_until_complete(task)
-    except Exception:
-        print("exception consumed")
+    asyncio.run(bug())
 
 .. seealso::