Style for docstring

[Cameron Simpson]

On 23Apr2022 03:26, Avi Gross <avigross at verizon.net> wrote:
>We know some people using "professional" language make things shorteror 
>talk from a point of view different than others and often in 
>otherwise incomprehensible jargon.
>If a programmer is taking about the algorithm that a function implements, then, yes, they may write "scan" and "return".
>But if they realize the darn documentation is for PEOPLE asking how to use the darn thing, and want to write in more informal and understandable English, I think it makes more sense to say what the function does as in "scans" and importantly what it "returns" to the user as a result.

I'm in the imperative camp. But if I think the function requires some 
elaboration, _then_ I provide description:

    def f(x):
        ''' Return the frobnangle of `x`.

            This iterates over the internals of `x` in blah order  
            gathering the earliest items which are frobby and composes a 
            nangle of the items.
        '''

I very much like the concise imperative opening sentence, sometimes 2 
sentences. Then the elaboration if the function isn't trivially obvious.

Cheers,
Cameron Simpson <cs at cskk.id.au>