Style for docstring

[2QdxY4RzWzUUiLuE at potatochowder.com]

On 2022-04-23 at 08:33:37 +1000,
Chris Angelico <rosuav at gmail.com> wrote:

> On Sat, 23 Apr 2022 at 08:24, <2QdxY4RzWzUUiLuE at potatochowder.com> wrote:
> >
> > On 2022-04-22 at 15:35:15 -0500,
> > "Michael F. Stemper" <michael.stemper at gmail.com> wrote:
> >
> > > On 22/04/2022 14.59, Chris Angelico wrote:
> > > > 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.
> > >
> > >
> > > >
> > > > I'd go with the third one, but "Return" rather than "Returns". Or
> > > > possibly "Test whether a permutation is even".
> > >
> > > "So let it be written. So let it be done."
> >
> > "Test whether a permutation is even," while technically factual, leaves
> > the reader to wonder what form the result takes, and what happens to
> > that result.
> 
> While it's definitely possible to have other results and other ways to
> deliver them, the return of a boolean would be the most obvious
> default.

Maybe, depending on the context and purpose of the application.

> > Do you want callers of the function also to assume that True means that
> > the permutation is even?  There are other reasonable strategies, such as
> > an enumerated type (whose items are Even, Odd, and FileNotFound), or
> > throwing an exception if the permutation is odd.
> 
> I'm assuming that the function is called something like "is_even()"
> and that it either is a method on a permutation object, or its
> parameters make it very clear what the permutation is.
> 
> If it returns an enumeration, I would say that in the docstring. If
> the docstring doesn't say, I would assume it returns True or False.

I think we're agreeing, but the OP didn't provide that information.
I've seen enough oddball (yes, that's my professional opinion :-)) APIs
(and worked with enough programmers from enough backgrounds) to know
that "most obvious default" is subjective.

> > I prefer the "return" (rather than "returns") version of the third
> > option.  Assuming that the programmers are familiar with the domain,
> > the other two leave out important information.

[...]

> We don't need to say "Figures out algorithmically whether the
> permutation is even. If it is, will return True; if it isn't, will
> return False; if something goes wrong, will raise an exception". This
> is Python; we know that if something goes wrong, an exception is
> raised. (Though it can help to say WHICH exception will be raised
> under WHAT circumstances). Some things are obvious.

No, we don't need to say it that way.  I believe that we do need to say
what the function returns under what circumstances.

If, in fact, the function in question is named is_permutation_even, then
it *is* as simple as the OP's third option, but not simpler.