[Python-Dev] Best practice for documentation for std lib

[Terry Reedy]

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