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

Terry Reedy tjreedy at udel.edu
Sat Sep 28 22:19:44 CEST 2013

On 9/22/2013 10:44 PM, Guido van Rossum wrote:

On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <tjreedy at udel.edu

('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.

I wrote 'current convention' not just as a statistical statement, but as a prescription I had read, even though I did not remember just where. PEP8 says "PEP 257 describes good docstring conventions." I followed that clue found the statement I had read. PEP 257 says ''' It [the one line docstring] prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...". ''' Whether the reference in PEP 8 makes it a PEP 8 rule? or a 'strict stdlib position'?

http://bugs.python.org/issue19067 proposes to change rangeobject docstrings. Is that OK or should the issue be rejected and closed?

-- Terry Jan Reedy

More information about the Python-Dev mailing list