[Python-Dev] Fwd: [python-tulip] Need help to finish asyncio documentation

[Russell E. Owen]

In article 
<CAP7+vJKmBPYU_E+4TyC3X6oFC_ydmd9K9PXk8atoLL6oJ_8FeA at mail.gmail.com>,
 Guido van Rossum <guido at python.org> wrote:

> We could really use more help reviewing and finishing asyncio's docs!
...
> http://docs.python.org/dev/library/asyncio.html

I think the documentation desperately needs an overview. I find it very 
confusing without one. I guess the links to PEPs are intended to be 
that, but it would be much more helpful to include the overview in the 
documentation.

I think a bit of re-ordering of topics could also help:
- One of the first things presented is a discussion of event loop 
policy, even though most users will never need to change the policy. 
Couldn't this go at the end?
- It tells how to create and set event loops, with no hint as to why one 
would want to do that. Is it common to have multiple event loops? A 
related oddity: what is the point of 
BaseEventLoop.run_until_complete(future)? It sounds interesting but 
obscure (unless it applies to one of many event loops).

In other words: if it was possible to show basic usage of event loops 
early, then discuss how to do the fancy stuff (new event loops, new even 
loop policies later) that might help.

BaseEventLoop.stop() says:
"Every callback scheduled before stop() is called will run."
but it does not say WHEN it will run -- immediately due to the stop, or 
normally as if stop was never called?

That said, I am very excited to have this functionality. I have been 
sticking with Python 2 for now, but this feature may entice me to make 
the switch.

-- Russell


> 
> ---------- Forwarded message ----------
> From: Victor Stinner <victor.stinner at gmail.com>
> Date: Sat, Feb 8, 2014 at 2:38 PM
> Subject: [python-tulip] Need help to finish asyncio documentation
> To: python-tulip <python-tulip at googlegroups.com>
> 
> 
> Hi,
> 
> I wrote most parts of the documentation of the asyncio module, but I'm
> not sure that anyone already read it yet. Can you please at least take
> at look?
> http://docs.python.org/dev/library/asyncio.html
> 
> Tell me if the documentation needs more examples. I don't want to add
> whole applications, only very short examples to explain one feature or
> concept, or show how to use one specific API.
> 
> I just realized that add/remove_reader/writer() methods of the event
> loop were not documented, sock_recv/sendall/accept/connect() methods
> neither. I documented them.
> 
> There are still many functions which only have "XXX" for documentation.
> 
> If you would like to contribute, send patches on .rst files. The
> source of the documentation is in the Doc/library/ directory of
> CPython repository:
> http://hg.python.org/cpython/
> 
> Files asyncio-*.rst:
> http://hg.python.org/cpython/file/default/Doc/library
> 
> Victor