Although the new generator methods introduced in PEP 342 are documented, the term "coroutine" is not defined anywhere. In particular, the fact that Python coroutines work in conjunction with an event loop rather than transferring control directly between each other is not mentioned.

I suspect the patch is out of date due to PEP 492 and Issue 24180 (“await” syntax for coroutines). But maybe the current glossary entry could be refined to also mention generators.

Here is a new patch:

* Clarified some recent instances of “coroutine” as “native coroutine” (term taken from PEP 492)
* Put “coroutine” before “coroutine function” in the glossary.
* Merge “Use as coroutines” section into new coroutine compound statement documentation
* Add links to glossary entry
* Added one mention of the new “async” coroutines to “asyncio”. I understand this is meant to be supported in 3.5, but still needs more documentation work.

Personally, I'm OK with the wording in the 3.5.0b2 docs, as far as basic terminology and glossary-style information goes.

I think coroutines, async, and event loops are badly under-documented in the broader context, though - there is very little in the docs explaining the concepts and constraints[1] of Python's async features. Unfortunately, the people with the knowledge of the subject are likely to be too close to the details to be able to write beginner-level documentation, and beginners don't know enough (by definition) to do so. I'm trying to do some playing round with creating my own async framework to get a better understanding of how things should work, but it's slow going and honestly I don't feel I've got anything much I could write up at this point.

[1] For example, how Python's implementation differs from other languages or "theoretical" discussions of coroutines in the literature.

Okay. The biggest thing that concerns me at the moment to do with the term is that there are too many related but different, specific meanings, that I suspect could be confusing, including:

1. Generators (and presumably also the new “async” native coroutines), compatible with “asyncio”: <https://docs.python.org/3.5/library/asyncio-task.html#coroutines>

2. PEP 492 “native” coroutines: <https://docs.python.org/3.5/glossary.html#term-coroutine-function>

Okay maybe some of the new wording is not needed any more. I plan to try documenting some basic stuff about the new PEP 492 coroutines in Issue 24439. Maybe I will incorporate the “native coroutine” clarifications from my patch here at the same time.

While some of the proposed changes in this issue have been applied to the documentation under other issues, other changes have not been applied.  Is it still desirable to incorporate the other changes (such as native coroutine) or have the existing doc changes been enough to make this issue obsolete?

Thank you.

I'm OK that the basic glossary item is now covered. I don't know about any of the other issues Martin mentioned.

I've closed the issue as my original comment is addressed, but if Martin wants to reopen it to address his concerns, I'm OK with him doing that.