[docs] [issue24439] Feedback for awaitable coroutine documentation

[Martin Panter]

Martin Panter added the comment:

It seems that Issue 24400 may implement __await__() for native coroutine instances, making points 1, 2 and 4 mainly redundant. This would also bypass a fifth problem: the need for the mandatory yet largely useless send(None) argument.

I am posting async-doc.patch, with these changes:

* Distinguish between PEP 492’s “native coroutines” and other coroutines such as those already supported by asyncio and PEP 342 (“yield” expression and generator cleanup)
* Move “coroutine” before “coroutine function” in the glossary.
* Add links to “coroutine” glossary
* Point 3: Explain about “async” and “await” becoming reserved keywords after a “def” header line
* Part of point 2: List native coroutine instance methods and hint at relationship with generator iterator instances

Still to do: how to drive an awaitable coroutine. Currently it seems you have to call coro.send(None), but if the current patch for Issue 24400 were applied, I think it would become next(coro), so I will leave this for later.

----------
dependencies: +Awaitable ABC incompatible with functools.singledispatch
keywords: +patch
stage:  -> patch review
Added file: http://bugs.python.org/file39714/async-doc.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24439>
_______________________________________