Hi, I added :py:coroutinefunction: and :py:coroutinemethod: commands in the pyspecifics.py extensions of CPython documentation. I modified the asyncio documentation to annotate all coroutines.
Changeset: https://hg.python.org/cpython/rev/430a2b541709 The HTML doc will be regenerated in one hour: https://docs.python.org/dev/library/asyncio-eventloop.html#creating-connections Tell me if it's better. I checked all asyncio functions/methods using "yield from" have the @coroutine method. I found some missing decorators, see the issue: http://bugs.python.org/issue23456 Then I checked that all public functions/methods with the @coroutine decorator are correctly annotated in the documentation. Victor 2015-02-12 12:51 GMT+01:00 Luciano Ramalho <[email protected]>: > ABSTRACT > > I propose that every asyncio function that is a coroutine gets a > highly visible marker at the top of its entry in the documentation. > For example the entry for StreamWriter.drain() [1] should read: > > drain() -> {{coroutine}} > Let the write buffer of the underlying transport ... > > This is more visible than a sentence like "This method is a > coroutine." buried somewhere in its description. > > The notation "-> {{coroutine}}" is just a stand-in for now. The main > point is having some visible indicator that can be found without > scanning the entire entry. The notation should be used in addition to > the mention "This method is a coroutine." in the body of the function > documentation. > > [1] > https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.drain > > > PROPOSAL RATIONALE > > A big gotcha for users of asyncio is knowing which API functions are > coroutines and which aren't. For example, StreamWriter.write isn't, > but StreamWriter.drain is. > > If you are one of the designers or implementers of asyncio this may be > obvious, but for the rest of us it's not. > > Apparently David Beazley got bitten by this. Take a look at slide 102 > titled "Be on the lookout!" in his tutorial "Generators, the Final > Frontier" presented at PyCon 2014 [2] > > [2] http://www.dabeaz.com/finalgenerator/FinalGenerator.pdf > > The asyncio docs provide this information, usually with the phrase > "This method is a coroutine." near the end of the description of the > function. Other phrases are used, and they don't appear always at the > end of the entry. But they never appear right at the beginning. > > When the description is long, that's easy to look over. See > BaseEventLoop.create_connection [3]. BaseEventLoop.create_server [4]. > > [3] > https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.BaseEventLoop.create_connection > > [4] > https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.BaseEventLoop.create_server > > It would be very helpful to asyncio users if the crucial distinction > between coroutines and regular functions was made right at the start > of each entry in the API docs. > > > PROPOSAL IMPLEMENTATION > > The easiest thing to do right away would be to add a formula like > {{coroutine}} as the first word in the first paragraph of the > description for each function. The actual formula must be decided. The > sentence "This method is a coroutine." could be used for this. The > main point is to make it the first thing in the description of the > method. > > Ideally the notation should not be embedded in the text, but appear > besides the function name, for example: > > drain() -> {{coroutine}} > Let the write buffer of the underlying transport ... > > If some abbreviated notation like {{coroutine}} is adopted, the phrase > "This method is a coroutine." should be kept in the description for > clarity. > > What do you think? I am willing to file a bug and provide a patch if > you think this is worthwhile. > > Best, > > Luciano > > > -- > Luciano Ramalho > Twitter: @ramalhoorg > > Professor em: http://python.pro.br > Twitter: @pythonprobr
