<div dir="ltr">Curio uses `.. asyncfunction:: acquire` and it renders as `await acquire()` at least in the function definition.</div><br><div class="gmail_quote"><div dir="ltr">On Fri, 30 Jun 2017 at 03:36 Andrew Svetlov <<a href="mailto:andrew.svetlov@gmail.com">andrew.svetlov@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">I like "<span style="color:rgb(33,33,33)">two methods, `async acquire()` and `release()`"<br><br>Regarding to extra markups -- I created sphinxcontrib-asyncio [1] library for it. Hmm, README is pretty empty but we do use the libra</span>ry for documenting aio-libs and aiohttp [2] itself<br><br>We use ".. comethod:: connect(request)" for method and "cofunction" for top level functions.<div><br>Additional markup for methods that could be used as async context managers:<br><br><div>   .. comethod:: delete(url, **kwargs)</div><div>      :async-with:</div><div>      :coroutine:</div><div><br></div><div>and `:async-for:` for async iterators.<br><br></div><br>1. <a href="https://github.com/aio-libs/sphinxcontrib-asyncio" target="_blank">https://github.com/aio-libs/sphinxcontrib-asyncio</a> <br>2. <a href="https://github.com/aio-libs/aiohttp" target="_blank">https://github.com/aio-libs/aiohttp</a> <font color="#212121"><br></font></div></div><br><div class="gmail_quote"><div dir="ltr">On Fri, Jun 30, 2017 at 1:11 PM Dima Tisnek <<a href="mailto:dimaqq@gmail.com" target="_blank">dimaqq@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi all,<br>
<br>
I'm working to improve async docs, and I wonder if/how async methods<br>
ought to be marked in the documentation, for example<br>
library/async-sync.rst:<br>
<br>
""" ... It [lock] has two basic methods, `acquire()` and `release()`. ... """<br>
<br>
In fact, these methods are not symmetric, the earlier is asynchronous<br>
and the latter synchronous:<br>
<br>
Definitions are `async def acquire()` and `def release()`.<br>
Likewise user is expected to call `await .acquire()` and `.release()`.<br>
<br>
This is user-facing documentation, IMO it should be clearer.<br>
Although there are examples for this specific case, I'm concerned with<br>
general documentation best practice.<br>
<br>
Should this example read, e.g.:<br>
* two methods, `async acquire()` and `release()`<br>
or perhaps<br>
* two methods, used `await x.acquire()` and `x.release()`<br>
or something else?<br>
<br>
If there's a good example already Python docs or in some 3rd party<br>
docs, please tell.<br>
<br>
Likewise, should there be marks on iterators? async generators? things<br>
that ought to be used as context managers?<br>
<br>
Cheers,<br>
d.<br>
_______________________________________________<br>
Async-sig mailing list<br>
<a href="mailto:Async-sig@python.org" target="_blank">Async-sig@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/async-sig" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/async-sig</a><br>
Code of Conduct: <a href="https://www.python.org/psf/codeofconduct/" rel="noreferrer" target="_blank">https://www.python.org/psf/codeofconduct/</a><br>
</blockquote></div><div dir="ltr">-- <br></div><div data-smartmail="gmail_signature"><div dir="ltr"><div>Thanks,</div>Andrew Svetlov</div></div>
_______________________________________________<br>
Async-sig mailing list<br>
<a href="mailto:Async-sig@python.org" target="_blank">Async-sig@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/async-sig" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/async-sig</a><br>
Code of Conduct: <a href="https://www.python.org/psf/codeofconduct/" rel="noreferrer" target="_blank">https://www.python.org/psf/codeofconduct/</a><br>
</blockquote></div>