Style for docstring

[Rob Cliffe]

Well, de gustibus non est disputandum.  For me, the switch from the 
imperative mode to the descriptive mode produces a mild cognitive 
dissonance.
Best wishes
Rob Cliffe

On 25/04/2022 23:34, Cameron Simpson wrote:
> 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>