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

[Alexander Belopolsky]

On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy <tjreedy at udel.edu> wrote:

> > 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.)
>>
>
> My take is that 'Returns' describes to the programmer what the function
> (interpreter) does, while 'Return' says what the programmer says to the
> interpreter when using the function. I strongly prefer the directive form.


+1

I don't think "Returns bar." is a valid English sentence because it lacks
subject.  I would not mind

def foo():
      """returns bar"""

which I would read as "Function foo() returns bar," but in this case
"returns" should be in lower case.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130923/3264fc0a/attachment.html>