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

Alexander Belopolsky alexander.belopolsky at gmail.com
Mon Sep 23 21🔞01 CEST 2013

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>

More information about the Python-Dev mailing list