Hi all,
Sorry to wake up this old thread, but I'm used to autodoc. Does anyone
know if I there is an py:autocoroutine:: directive or something similar to
py:coroutinefunction::?
Thanks!
André
On Thursday, February 12, 2015 at 6:51:15 AM UTC-5, Luciano Ramalho wrote:
>
> 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
>
