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

MRAB python at mrabarnett.plus.com
Mon Sep 23 21:11:35 CEST 2013


On 23/09/2013 20:01, Terry Reedy wrote:
> 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.
>
<pedantic>I think you mean "imperative" vs "indicative".</pedantic>


More information about the Python-Dev mailing list