Style for docstring

[Chris Angelico]

On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
<michael.stemper at gmail.com> wrote:
>
> I'm writing a function that is nearly self-documenting by its name,
> but still want to give it a docstring. Which of these would be
> best from a stylistic point of view:
>
>
>    Tells caller whether or not a permutation is even.
>
>    Determines if a permutation is even. (Alternative is that it's odd.)
>
>    Returns True if permutation is even, False if it is odd.
>
>
> (Before somebody suggests it, I'm not going to put six weeks' worth
> of a course in group theory in there to help somebody who doesn't
> know what those standard terms mean.)
>

I'd go with the third one, but "Return" rather than "Returns". Or
possibly "Test whether a permutation is even".

That's just one opinion though, others may disagree :)

ChrisA