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

miss-islington · aeros · 1st1 · commit 2eb1dac46e25 · 2019-09-30T18:47:13.000-07:00
(cherry picked from commit e407013) Co-authored-by: Kyle Stanley <aeros167@gmail.com>
diff --git 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
@@ -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
@@ -6,7 +6,7 @@
 
 
 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():
