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.


On Jun 30, 2017, 6:11 AM -0400, Dima Tisnek <dimaqq@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

""" ... 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?

Async-sig mailing list
Code of Conduct: https://www.python.org/psf/codeofconduct/