In article <cap7+vjkmbpyu_e+4tyc3x6ofc_ydmd9k9pxk8atoll6oj_8...@mail.gmail.com>, Guido van Rossum <gu...@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.stin...@gmail.com> > Date: Sat, Feb 8, 2014 at 2:38 PM > Subject: [python-tulip] Need help to finish asyncio documentation > To: python-tulip <python-tu...@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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
