On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjre...@udel.edu> wrote:
> On 9/22/2013 10:04 PM, Guido van Rossum wrote:
>
> If I had the final word, I'd recommend using the current docstrings as
>> the .rst contents and replacing the docstrings with the 1-2 line
>> function descriptions from the PEP, e.g.:
>>
>> * median(data) -> median (middle value) of data, taking the
>> average of the two middle values when there are an even
>> number of values.
>>
>> But omitting the signature proper, and replacing "->" with "Returns" or
>> "Returns the". E.g.
>>
>> def median(data):
>> """Returns the median (middle value) of data, taking the
>> average of the two middle values when there are an even
>> number of values.
>> """
>> ...
>>
>> I'd personally also rewrite them all so that the first line of the
>> docstring is a phrase that can stand by itself, as I describe in PEP 8,
>> but this is used only sporadically in the stdlib.
>>
>
> I am gradually changing Idle docstrings, though only Idle developers will
> ever see them. Writing a 60 char summary forces a clear understanding of
> the function. Applied to the above.
>
> def median(data):
> """Return the median (middle value) of data.
>
> Use the average of the two middle values when
>
> there are an even number of values.
> """
>
Glad you like it. I still do, too, but I've given up hope to convince all
core developers to stick to this style. :-(
> ('Return' rather than 'Returns' is the current convention.)
>
That's actually a religious argument which in the stdlib takes no strict
position -- a quick grep shows that both are used, although 'Return' is
more frequent by a 5-to-1 margin. IIRC in the Java world you *have* to use
'Returns', but I don't buy the argument from nit-picky grammarians that
leads to this rule. (It's something about the documentation not being a
command. But English is more flexible than that.)
--
--Guido van Rossum (python.org/~guido)
_______________________________________________
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
