[docs] Feedback for awaitable coroutine documentation (issue 24439)

[vadmium+py at gmail.com]

Reviewers: Yury.Selivanov,


https://bugs.python.org/review/24439/diff/15090/Doc/library/asyncio-task.rst
File Doc/library/asyncio-task.rst (right):

https://bugs.python.org/review/24439/diff/15090/Doc/library/asyncio-task.rst#newcode11
Doc/library/asyncio-task.rst:11: A :term:`coroutine` is
:term:`generator` that follows certain conventions.  For
On 2015/06/22 20:23:12, Yury.Selivanov wrote:
> Again, no need to reference "coroutine" term here. Coroutines in
asyncio is a
> bit broader thing than 'async def' coroutine objects defined in the
glossary. 

In my upcoming patch I have reworded this so that the glossary reference
is used in the context of native coroutines.

> We need a separate sub-section for native coroutines though.

So far, I have kept it all in the one section but expanded it to cover
both using native Python coroutines and generator-based coroutines.

https://bugs.python.org/review/24439/diff/15090/Doc/library/dis.rst
File Doc/library/dis.rst (right):

https://bugs.python.org/review/24439/diff/15090/Doc/library/dis.rst#newcode516
Doc/library/dis.rst:516: returns ``o`` if ``o`` is a native coroutine
object, or resolves
On 2015/06/22 20:23:12, Yury.Selivanov wrote:
> .. if ``o`` is a native or generator-based coroutine object ..

Replacing with “native coroutine object or one derived from
:func:`types.coroutine` ”, to avoid confusing with PEP 342 and asyncio
generator-based coroutines.

https://bugs.python.org/review/24439/diff/15090/Doc/library/types.rst
File Doc/library/types.rst (right):

https://bugs.python.org/review/24439/diff/15090/Doc/library/types.rst#newcode283
Doc/library/types.rst:283: compatible with native coroutines.
On 2015/06/22 20:23:12, Yury.Selivanov wrote:
> This bit was also updated, please rebase.

I don’t think anything got changed here. Did you have anything in mind?

I intend to add that the returned objects are awaitable, but do not
implement __await__().

https://bugs.python.org/review/24439/diff/15090/Doc/reference/datamodel.rst
File Doc/reference/datamodel.rst (right):

https://bugs.python.org/review/24439/diff/15090/Doc/reference/datamodel.rst#newcode629
Doc/reference/datamodel.rst:629: Native coroutine objects are similar to
the objects returned by
On 2015/06/22 20:23:12, Yury.Selivanov wrote:
> Since we've merged issue 24400, I think we need to briefly document
each of
> those methods (send, close, throw) with references to generators docs
for more
> details.

I’m thinking of putting a proper full explanation of each method in a
new Native Coroutine Objects subsection near the bottom.



Please review this at https://bugs.python.org/review/24439/

Affected files:
  Doc/glossary.rst
  Doc/howto/functional.rst
  Doc/library/asyncio-task.rst
  Doc/library/asyncio.rst
  Doc/library/collections.abc.rst
  Doc/library/dis.rst
  Doc/library/inspect.rst
  Doc/library/sys.rst
  Doc/library/types.rst
  Doc/reference/compound_stmts.rst
  Doc/reference/datamodel.rst
  Doc/reference/expressions.rst