docs refactoring

docs refactoring

[GvR, 2014-02-20 19:53:31]

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop.rst
File Doc/library/asyncio-eventloop.rst (right):

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:391: which result is set to ``None`` on
success.
which -> whose

Also no comma needed on the previous line.

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:394: much data, if any, was successfully sent.
This is correct, but I expect that people will believe it to be a bug and try to
"fix" it. That's of course impossible because giving the data to the kernel
doesn't mean the other side received it -- you'd need an end to end conformation
before you can know that it was truly received. I wonder if we can add a note
clarifying this here by rephrasing it as "how much data, if any, was
successfully processed by the receiving end of the connection."

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:441: returns a :class:`Future`.
Hmm... Can we under-specify this and state that it can return either a future or
a coroutine? Actually I would like to do that for (almost) *any* defined method
or function in the API that is a coroutine or returns a Future -- we really
should warn our users that this aspect of the spec is fungible. Or perhaps we
can document this once in the definition to which "coroutine" links, and then
(again, with a few obvious exceptions, e.g. async() itself :-) document
everything as "a coroutine" even if the implementation currently returns a
Future?

[yselivanov, 2014-02-20 20:32:14]

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop.rst
File Doc/library/asyncio-eventloop.rst (right):

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:391: which result is set to ``None`` on
success.
On 2014/02/20 19:53:31, GvR wrote:
> which -> whose
> 
> Also no comma needed on the previous line.

OK

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:394: much data, if any, was successfully sent.
On 2014/02/20 19:53:31, GvR wrote:
> This is correct, but I expect that people will believe it to be a bug and try
to
> "fix" it. That's of course impossible because giving the data to the kernel
> doesn't mean the other side received it -- you'd need an end to end
conformation
> before you can know that it was truly received. I wonder if we can add a note
> clarifying this here by rephrasing it as "how much data, if any, was
> successfully processed by the receiving end of the connection."

OK, much better with this change

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:441: returns a :class:`Future`.
On 2014/02/20 19:53:31, GvR wrote:
> Hmm... Can we under-specify this and state that it can return either a future
or
> a coroutine? Actually I would like to do that for (almost) *any* defined
method
> or function in the API that is a coroutine or returns a Future -- we really
> should warn our users that this aspect of the spec is fungible.

But what if someone prefer to use asyncio without coroutines? Strictly callback
approach. They may find 'getaddrinfo()' function useful, and start using its
result as a Future, i.e. add/remove callbacks on it etc.

> Or perhaps we
> can document this once in the definition to which "coroutine" links, and then
> (again, with a few obvious exceptions, e.g. async() itself :-) document
> everything as "a coroutine" even if the implementation currently returns a
> Future?

That could work. But again, people will look in the source code, and if they
see that a future is returned, they might start using its APIs. And even with
this remark in docs, it will be hard for us to change return value from Future
to coroutine, or vice versa.

[GvR, 2014-02-20 20:37:54]

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop.rst
File Doc/library/asyncio-eventloop.rst (right):

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:441: returns a :class:`Future`.
On 2014/02/20 20:32:14, yselivanov wrote:
> On 2014/02/20 19:53:31, GvR wrote:
> > Hmm... Can we under-specify this and state that it can return either a
future
> or
> > a coroutine? Actually I would like to do that for (almost) *any* defined
> method
> > or function in the API that is a coroutine or returns a Future -- we really
> > should warn our users that this aspect of the spec is fungible.
> 
> But what if someone prefer to use asyncio without coroutines? Strictly
callback
> approach. They may find 'getaddrinfo()' function useful, and start using its
> result as a Future, i.e. add/remove callbacks on it etc.

That's what async() is for.

> > Or perhaps we
> > can document this once in the definition to which "coroutine" links, and
then
> > (again, with a few obvious exceptions, e.g. async() itself :-) document
> > everything as "a coroutine" even if the implementation currently returns a
> > Future?
> 
> That could work. But again, people will look in the source code, and if they
> see that a future is returned, they might start using its APIs. And even with
> this remark in docs, it will be hard for us to change return value from Future
> to coroutine, or vice versa.

I went back and forth a few times for various functions/methods during
development and it was mostly a non-event each time. This is also why I prefer
to document (almost) everything as "a coroutine", since that's the more
conservative assumption.

[yselivanov, 2014-02-20 20:46:45]

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop.rst
File Doc/library/asyncio-eventloop.rst (right):

https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
Doc/library/asyncio-eventloop.rst:441: returns a :class:`Future`.
> I went back and forth a few times for various functions/methods during
> development and it was mostly a non-event each time. This is also why I prefer
> to document (almost) everything as "a coroutine", since that's the more
> conservative assumption.


So what do you suggest?

If a method/function is decorated with a @coroutine decorator, we
write "The method is a coroutine"

If a method/function returns a Future, we write
"The method returns a coroutine object"

?

[GvR, 2014-02-20 20:50:38]

On 2014/02/20 20:46:45, yselivanov wrote:
>
https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop.rst
> File Doc/library/asyncio-eventloop.rst (right):
> 
>
https://codereview.appspot.com/66430046/diff/1/Doc/library/asyncio-eventloop....
> Doc/library/asyncio-eventloop.rst:441: returns a :class:`Future`.
> > I went back and forth a few times for various functions/methods during
> > development and it was mostly a non-event each time. This is also why I
prefer
> > to document (almost) everything as "a coroutine", since that's the more
> > conservative assumption.
> 
> 
> So what do you suggest?
> 
> If a method/function is decorated with a @coroutine decorator, we
> write "The method is a coroutine"
> 
> If a method/function returns a Future, we write
> "The method returns a coroutine object"
> 
> ?

I suggest always writing "it is a coroutine" and stretching the meaning of
coroutine.

[yselivanov, 2014-02-20 21:08:48]

> I suggest always writing "it is a coroutine" and stretching the meaning of
> coroutine.


OK, please review the new version.

[GvR, 2014-02-20 21:16:42]

LGTM. Poor Larry!