
<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title></title>

</head>

<body>

<div name="messageBodySection" style="font-size: 14px; font-family: -apple-system, BlinkMacSystemFont, sans-serif;">Hi Dima,

<div><br /></div>

<div>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.</div>

</div>

<div name="messageSignatureSection" style="font-size: 14px; font-family: -apple-system, BlinkMacSystemFont, sans-serif;"><br />

Thanks,<br />

Yury</div>

<div name="messageReplySection" style="font-size: 14px; font-family: -apple-system, BlinkMacSystemFont, sans-serif;"><br />

On Jun 30, 2017, 6:11 AM -0400, Dima Tisnek <dimaqq@gmail.com>, wrote:<br />

<blockquote type="cite" style="margin: 5px 5px; padding-left: 10px; border-left: thin solid #1abc9c;">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 />

Async-sig@python.org<br />

https://mail.python.org/mailman/listinfo/async-sig<br />

Code of Conduct: https://www.python.org/psf/codeofconduct/<br /></blockquote>

</div>

</body>

</html>