pep-0492: More info on __cocall__; Add a section about coroutine-generators

pep-0492.txt

@@ -737,10 +737,34 @@ Differences from this proposal:
    addresses this problem with a different approach, see `Debugging
    Features`_.
 
-5. There are no equivalents of ``async for`` and ``async with`` in PEP
+5. A shortcoming of requiring a ``cocall`` keyword to call a coroutine
+   is that if is decided to implement coroutine-generators --
+   coroutines with ``yield`` or ``async yield`` expressions -- we
+   wouldn't need a ``cocall`` keyword to call them.  So we'll end up
+   having ``__cocall__`` and no ``__call__`` for regular coroutines,
+   and having ``__call__`` and no ``__cocall__`` for coroutine-
+   generators.
+
+6. There are no equivalents of ``async for`` and ``async with`` in PEP
    3152.
 
 
+Coroutine-generators
+--------------------
+
+With ``async for`` keyword it is desirable to have a concept of a
+*coroutine-generator* -- a coroutine with ``yield`` and ``yield from``
+expressions.  To avoid any ambiguity with regular generators, we would
+likely require to have an ``async`` keyword before ``yield``, and
+``async yield from`` would raise a ``StopAsyncIteration`` exception.
+
+While it is possible to implement coroutine-generators, we believe that
+they are out of scope of this proposal.  It is an advanced concept that
+should be carefully considered and balanced, with a non-trivial changes
+in the implementation of current generator objects.  This is a matter
+for a separate PEP.
+
+
 No implicit wrapping in Futures
 -------------------------------