Fix and improve `asyncio.run()` docs (GH-16403)

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index e601e8b369841044ab6ab1e6e8e7819b3d004cf6..9ce0357f1cb42415e9241b966a21ae0dfe76e8dc 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -247,7 +247,7 @@ Glossary
       Fortran contiguous arrays, the first index varies the fastest.
 
    coroutine
-      Coroutines is a more generalized form of subroutines. Subroutines are
+      Coroutines are a more generalized form of subroutines. Subroutines are
       entered at one point and exited at another point.  Coroutines can be
       entered, exited, and resumed at many different points.  They can be
       implemented with the :keyword:`async def` statement.  See also

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 9f55a3534a5e0c8842261730c7a499b387260419..155887a3ab3af9dc2abf6e58bab48e2fc088b665 100644 (file)
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -212,6 +212,8 @@ Running an asyncio Program
 
 .. function:: run(coro, \*, debug=False)
 
+    Execute the :term:`coroutine` *coro* and return the result.
+
     This function runs the passed coroutine, taking care of
     managing the asyncio event loop, *finalizing asynchronous
     generators*, and closing the threadpool.
@@ -225,10 +227,6 @@ Running an asyncio Program
     the end.  It should be used as a main entry point for asyncio
     programs, and should ideally only be called once.
 
-    Return a result of *coro* execution, or raise a :exc:`RuntimeError`
-    if ``asyncio.run()`` is called from a running event loop, or a
-    :exc:`ValueError` if *coro* is not a courutine.
-
     Example::
 
         async def main():

diff --git a/Lib/asyncio/runners.py b/Lib/asyncio/runners.py
index 904102bf82bef4f517b139fdd9ccb9902dc70d19..03ce33300eba8316f849e0d9e9cee0c4d5088c88 100644 (file)
--- a/Lib/asyncio/runners.py
+++ b/Lib/asyncio/runners.py
@@ -6,7 +6,7 @@ from . import tasks
 
 
 def run(main, *, debug=False):
-    """Run a coroutine.
+    """Execute the coroutine and return the result.
 
     This function runs the passed coroutine, taking care of
     managing the asyncio event loop and finalizing asynchronous
@@ -21,10 +21,6 @@ def run(main, *, debug=False):
     It should be used as a main entry point for asyncio programs, and should
     ideally only be called once.
 
-    Return a result of *coro* execution, or raise a RuntimeError
-    if `asyncio.run()`is called from a running event loop, or a ValueError
-    if `main` is not a courutine.
-
     Example:
 
         async def main():