Martin, Thanks for the update! My main concern with this version is about introducing the "native coroutine" terminology. While it was a necessary thing to do in PEP 492, I really doubt that we should use it in Python docs. http://bugs.python.org/review/24439/diff/15143/Doc/glossary.rst File Doc/glossary.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/glossary.rst#newcode181 Doc/glossary.rst:181: coroutine function` is defined with the :keyword:`async def` statement, Martin, I'm not sure we should use the "native coroutine" term. I'd really prefer to just use "coroutine" for "async def"/"await" objects, and "generator-based coroutine" for "yield & yield from" ones. 99% of people don't use generators as coroutines (at least directly). Some Python users know that generators can be coroutines, but that's mostly those who use asyncio/twisted/tornado frameworks. In asyncio we have a "coroutine" decorator, that in a sense, "converts" a generator into a coroutine. Hopefully, in the near future, Python users won't use generators as coroutines, and I don't want them to be confused why we have the "native" terminology. http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst File Doc/library/asyncio-task.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst#... Doc/library/asyncio-task.rst:16: :func:`@asyncio.coroutine <asyncio.coroutine>`. This is mainly "Documentation purposes" is one thing. Another is compatibility with native coroutines. If you have a coroutine: def foo(): yield from o and a native coroutine bar: async def bar(): await foo() Then you have to decorate 'foo' with "asyncio.coroutine". Otherwise it's not going to work. I'd say that it's encouraged to use the decorator on generator-based coroutine functions for documentation purposes *and* for compatibility with PEP 492 coroutines. http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst#... Doc/library/asyncio-task.rst:70: the generator to call native coroutines. Let's also explicitly state that there is no need to decorate 'async def' functions. http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst#... Doc/library/asyncio-task.rst:94: async def hello_world(): I think we should leave one example of generator based coroutines... http://bugs.python.org/review/24439/diff/15143/Doc/library/collections.abc.r... File Doc/library/collections.abc.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/library/collections.abc.r... Doc/library/collections.abc.rst:169: the generator methods defined in :pep:`342`, namely: Since we now have a dedicated section for coroutines in datamodel.rst we need to update these refs to "coroutine.send" etc. http://bugs.python.org/review/24439/diff/15143/Doc/library/dis.rst File Doc/library/dis.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/library/dis.rst#newcode52... Doc/library/dis.rst:525: one derived from :func:`types.coroutine`, or resolves This isn't right too. types.coroutine either patches the generator function's code object, or wraps it in a special object with __await__. Since this is a pretty low level documentation, let's just rephrase it to something like this: [...] returns ``o`` if ``o`` is a native coroutine object or a generator object with CO_ITERABLE_COROUTINE flag, or resolves [...] http://bugs.python.org/review/24439/diff/15143/Doc/library/types.rst File Doc/library/types.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/library/types.rst#newcode... Doc/library/types.rst:293: it may not necessarily implement the :meth:`__await__` method. Please take a look at my other patch: http://bugs.python.org/review/24325/patch/15133/57450 Ideally we should combine the two http://bugs.python.org/review/24439/diff/15143/Doc/reference/datamodel.rst File Doc/reference/datamodel.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/reference/datamodel.rst#n... Doc/reference/datamodel.rst:2278: Native :term:`coroutine` objects are awaitable. The :term:`generator Let's wrap "The :term:`generator [..]" in a ".. note::" section? http://bugs.python.org/review/24439/diff/15143/Doc/reference/datamodel.rst#n... Doc/reference/datamodel.rst:2296: Native Coroutine Objects Again, I'd prefer to drop "Native" http://bugs.python.org/review/24439/diff/15143/Objects/genobject.c File Objects/genobject.c (right): http://bugs.python.org/review/24439/diff/15143/Objects/genobject.c#newcode91... Objects/genobject.c:913: {"close",(PyCFunction)coro_wrapper_close, METH_NOARGS, coro_close_doc}, Please rebase your patch -- this code was updated in 24400. http://bugs.python.org/review/24439/