[Python-Dev] Best practice for documentation for std lib
alexander.belopolsky at gmail.com
Mon Sep 23 21:18: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.
I don't think "Returns bar." is a valid English sentence because it lacks
subject. I would not mind
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...
More information about the Python-Dev