I like "two methods, `async acquire()` and `release()`"
Regarding to extra markups -- I created sphinxcontrib-asyncio  library for it. Hmm, README is pretty empty but we do use the library for documenting aio-libs and aiohttp  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.
On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek firstname.lastname@example.org wrote:
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()`
- 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 Asyncemail@example.com https://mail.python.org/mailman/listinfo/async-sig Code of Conduct: https://www.python.org/psf/codeofconduct/