[Async-sig] async documentation methods

[Yury Selivanov]

Hi Dima,

Have you seen https://github.com/asyncio-docs?  I'm trying to get some work going there to improve asyncio docs in 3.7. Will start committing more of my time there soon.

Thanks,
Yury

On Jun 30, 2017, 6:11 AM -0400, Dima Tisnek <dimaqq at gmail.com>, wrote:
> Hi all,
>
> I'm working to improve async docs, and I wonder if/how async methods
> ought to be marked in the documentation, for example
> library/async-sync.rst:
>
> """ ... It [lock] has two basic methods, `acquire()` and `release()`. ... """
>
> In fact, these methods are not symmetric, the earlier is asynchronous
> and the latter synchronous:
>
> Definitions are `async def acquire()` and `def release()`.
> Likewise user is expected to call `await .acquire()` and `.release()`.
>
> This is user-facing documentation, IMO it should be clearer.
> Although there are examples for this specific case, I'm concerned with
> general documentation best practice.
>
> Should this example read, e.g.:
> * two methods, `async acquire()` and `release()`
> or perhaps
> * two methods, used `await x.acquire()` and `x.release()`
> or something else?
>
> If there's a good example already Python docs or in some 3rd party
> docs, please tell.
>
> Likewise, should there be marks on iterators? async generators? things
> that ought to be used as context managers?
>
> Cheers,
> d.
> _______________________________________________
> Async-sig mailing list
> Async-sig at python.org
> https://mail.python.org/mailman/listinfo/async-sig
> Code of Conduct: https://www.python.org/psf/codeofconduct/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/async-sig/attachments/20170630/cb59202b/attachment.html>