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

(cherry picked from commit e407013089259e4c0b271703e1975bbcd578a2d5)

Co-authored-by: Kyle Stanley <aeros167@gmail.com>

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 8af4373b11d7c9ea9c075cb050e430acc87f12d1..ed588612aeabed205b83db45ac447ad20db0b264 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -243,7 +243,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 a9f6f9cfc4b62604249bd309f92290a7f555cbce..9a4cda1887887c5dee0b6454dce1b81d9bc97228 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 and *finalizing asynchronous
     generators*.
@@ -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 df686386b8fd4ee3273e29f7e93e7701b0579b96..2e37e18b45fc150536f6deedfc388c30e8aa6410 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():