[Python-Dev] Best practice for documentation for std lib
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