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

[Terry Reedy]

On 9/22/2013 10:44 PM, Guido van Rossum wrote:

> Glad you like it. I still do, too, but I've given up hope to convince
> all core developers to stick to this style. :-(

 >[me]  ('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.

In the .rst docs, 'Return' versus 'Returns', exact uppercase word match, 
is a little over 3 to 1. I am sure I have seen 'Return' and similiar 
directive forms ('Print', 'Store', 'Compare', etc) recommended as 
current doc style, as prefered by the current doc crew.

 > 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. Why? For one thing, *because* it is different from normal 
descriptive text, such as the first sentence of this paragraph. For 
another, the descriptive form seems addressed to me as code reader while 
the directive form seems addressed to me as code writer. For me, the 
latter seems more energizing.

-- 
Terry Jan Reedy