I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library
for it. Hmm, README is pretty empty but we do use the library for
documenting aio-libs and aiohttp [2] itself
We use ".. comethod:: connect(request)" for method and "cofunction" for top
level functions.
Additional markup for methods that could be used as async context managers:
.. comethod:: delete(url, **kwargs)
:async-with:
:coroutine:
and `:async-for:` for async iterators.
1. https://github.com/aio-libs/sphinxcontrib-asyncio
2. https://github.com/aio-libs/aiohttp
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <dim...@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@python.org
> https://mail.python.org/mailman/listinfo/async-sig
> Code of Conduct: https://www.python.org/psf/codeofconduct/
>
--
Thanks,
Andrew Svetlov
_______________________________________________
Async-sig mailing list
Async-sig@python.org
https://mail.python.org/mailman/listinfo/async-sig
Code of Conduct: https://www.python.org/psf/codeofconduct/
