[issue40526] documentation bad on asyncio

[Kyle Stanley]

Kyle Stanley <aeros167 at gmail.com> added the comment:

I presume this is referring to the following example on the first page of the docs:

```
import asyncio

async def main():
    print('Hello ...')
    await asyncio.sleep(1)
    print('... World!')

# Python 3.7+
asyncio.run(main())
```

If so, the main purpose of that example is just to demonstrate basic async/await syntax, and show asyncio.run() for a trivial case to clearly show how it's used at a fundamental level; it's intentional that the more involved examples that demonstrate asynchronous programming are contained in https://docs.python.org/3/library/asyncio-task.html#coroutine. Also, the example is simple and condensed enough that it requires zero additional explanation or context, as should be the case for a simple "hello world" example. Consider the perspective of someone who found the page without having previously seen async/await syntax used.

FYI, in the future, I would highly recommend focusing more on the constructive parts when opening issues. Particularly the title "documentation bad on asyncio", provides zero context or usefulness. It also comes across as rather rude and unappreciative of the significant voluntary efforts that went into writing the documentation in the first place. Instead, something like "Improve example on front page of asyncio docs" is much more helpful.

----------
nosy: +aeros

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40526>
_______________________________________