On Thu, Feb 12, 2015 at 2:12 PM, Andrew Svetlov
<andrew.svet...@gmail.com> wrote:
> I like to have simple markup for coroutines but -1 for using return
> annotation for that.
> Return annotation is for return value description, not for function itself.
Perhaps we need a variation of the return value notation for generator
functions and coroutines.
It is a fact that when you call a coroutine what you get is a
coroutine object, just as it is the case that when you call a
generator function what you get is a generator object. The fact that
generator objects can now actually return a value complicates the
matter (and shows that the -> notation used in signatures is
inadequate to express modern Python semantics).
I was trying to solve this issue when I added {{ }} around
{{coroutine}}. Like I said, it's just a stand-in. I agree it looks
like a set with a set (though sets can't actually have sets as
elements -- they're unhashable).
Perhaps <> would be better:
drain() -> <coroutine>
Cheers,
Luciano
PS. The Python docs overloads the [ ] for optional arguments. Once I
saw a person think it is a list, so that is not good either. ;-)
>
> On Thu, Feb 12, 2015 at 6:06 PM, Victor Stinner
> <victor.stin...@gmail.com> wrote:
>> Hi,
>>
>> 2015-02-12 12:51 GMT+01:00 Luciano Ramalho <luci...@ramalho.org>:
>>> This is more visible than a sentence like "This method is a
>>> coroutine." buried somewhere in its description.
>>
>> We should keep this sentence *and* add the return type in the doc.
>>
>> I tried to add " -> coroutine":
>>
>> .. method:: BaseEventLoop.create_connection(...) -> coroutine
>>
>> It works in Sphinx. But I don't know if it is the chosen syntax to
>> indicate the return type.
>>
>>> The notation "-> {{coroutine}}" is just a stand-in for now.
>>
>> I don't understand "{{". It looks like a set of set. I prefer just "->
>> coroutine".
>>
>> Victor
>
>
>
> --
> Thanks,
> Andrew Svetlov
--
Luciano Ramalho
Twitter: @ramalhoorg
Professor em: http://python.pro.br
Twitter: @pythonprobr
