[Python-Dev] Best practice for documentation for std lib

[Guido van Rossum]

On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy at 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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/8eb6438d/attachment-0001.html>