[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