[Python-Dev] Best practice for documentation for std lib
Terry Reedy
tjreedy at udel.edu
Mon Sep 23 04:25:57 CEST 2013
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.
"""
('Return' rather than 'Returns' is the current convention.)
--
Terry Jan Reedy
More information about the Python-Dev
mailing list