Issue #24439: Improve PEP 492 related docs.

Patch by Martin Panter.

1 files changed, 15 insertions, 10 deletions

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index c73e886..76b3850 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -666,15 +666,9 @@ can be used to create instance variables with different implementation details.
 Coroutines
 ==========
 
-.. index::
-   statement: async def
-   statement: async for
-   statement: async with
-   keyword: async
-   keyword: await
-
 .. versionadded:: 3.5
 
+.. index:: statement: async def
 .. _`async def`:
 
 Coroutine function definition
@@ -683,14 +677,23 @@ Coroutine function definition
 .. productionlist::
    async_funcdef: "async" `funcdef`
 
+.. index::
+   keyword: async
+   keyword: await
+
 Execution of Python coroutines can be suspended and resumed at many points
-(see :term:`coroutine`.)  :keyword:`await` expressions, :keyword:`async for`
-and :keyword:`async with` can only be used in their bodies.
+(see :term:`coroutine`).  In the body of a coroutine, any ``await`` and
+``async`` identifiers become reserved keywords; :keyword:`await` expressions,
+:keyword:`async for` and :keyword:`async with` can only be used in
+coroutine bodies.  However, to simplify the parser, these keywords cannot
+be used on the same line as a function or coroutine (:keyword:`def`
+statement) header.
 
 Functions defined with ``async def`` syntax are always coroutine functions,
 even if they do not contain ``await`` or ``async`` keywords.
 
-It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in coroutines.
+It is a :exc:`SyntaxError` to use :keyword:`yield` expressions in
+``async def`` coroutines.
 
 An example of a coroutine function::
 
@@ -699,6 +702,7 @@ An example of a coroutine function::
         await some_coroutine()
 
 
+.. index:: statement: async for
 .. _`async for`:
 
 The :keyword:`async for` statement
@@ -742,6 +746,7 @@ It is a :exc:`SyntaxError` to use ``async for`` statement outside of an
 :keyword:`async def` function.
 
 
+.. index:: statement: async with
 .. _`async with`:
 
 The :keyword:`async with` statement