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

[yselivanov at gmail.com]

http://bugs.python.org/review/24439/diff/15090/Doc/howto/functional.rst
File Doc/howto/functional.rst (right):

http://bugs.python.org/review/24439/diff/15090/Doc/howto/functional.rst#newcode611
Doc/howto/functional.rst:611: a more generalized form of subroutines.
I don't think we need a reference to the term here.  Coroutines defined
in the glossary section are what 'async def' functions return, not a
generic definition.

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

http://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
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. 

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

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

http://bugs.python.org/review/24439/diff/15090/Doc/library/asyncio.rst#newcode21
Doc/library/asyncio.rst:21: code using :term:`coroutines <coroutine>`,
Remove the ref, please.

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

http://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
.. if ``o`` is a native or generator-based coroutine object ..

If you look at _PyCoro_GetAwaitableIter you'll see that it tests
PyCoro_CheckExact *or* (PyCoro_CheckExact && CO_ITERABLE_COROUTINE)

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

http://bugs.python.org/review/24439/diff/15090/Doc/library/inspect.rst#newcode294
Doc/library/inspect.rst:294: Return true if the object is a native
Please rebase your patch on top of the most recent default branch. I
think I've updated some of these docs already.

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

http://bugs.python.org/review/24439/diff/15090/Doc/library/types.rst#newcode283
Doc/library/types.rst:283: compatible with native coroutines.
This bit was also updated, please rebase.

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

http://bugs.python.org/review/24439/diff/15090/Doc/reference/compound_stmts.rst#newcode671
Doc/reference/compound_stmts.rst:671: Coroutines may also be implemented
using :term:`generators <generator>`,
I don't think we need a reference to generators here, it's not relevant
to the new syntax (at least in this particular file).

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

http://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
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.

http://bugs.python.org/review/24439/