[Python-Dev] Best practice for documentation for std lib (original) (raw)

Guido van Rossum guido at python.org
Mon Sep 23 04:44:09 CEST 2013

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>

More information about the Python-Dev mailing list