bug#24706: 26.0.50; Minor mode functions should do strict argument type checking

[Philipp Stephani <p.stephani2@gmail.com>]

Am Mi., 26. Apr. 2017 um 13:27 Uhr schrieb Eli Zaretskii <eliz@gnu.org>:
>
> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Sun, 23 Apr 2017 17:51:32 +0000
> > Cc: drew.adams@oracle.com, 24706@debbugs.gnu.org
> >
> > Eli Zaretskii <eliz@gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:
> >
> >  > From: Philipp Stephani <p.stephani2@gmail.com>
> >  > Date: Sun, 16 Oct 2016 18:25:08 +0000
> >  >
> >  > Attached a patch that uses the wording from `define-minor-mode'.
> >
> >  The patch for the ELisp manual simply rearranges the same words, so
> >  it's not clear to me why we would prefer it to what's already there.
> >
> > I don't think there's any repetition or rearranging here.
>
> Here's the ELisp manual part of your proposed change:
>
>    If the mode command is called from Lisp (i.e., non-interactively), it
>   -should enable the mode if the argument is omitted or @code{nil}; it
>   -should toggle the mode if the argument is the symbol @code{toggle};
>   -otherwise it should treat the argument in the same way as for an
>   -interactive call with a numeric prefix argument, as described above.
>   +should toggle the mode if the argument is the symbol @code{toggle}; it
>   +should disable the mode if the argument is a non-positive integer;
>   +otherwise, e.g., if the argument is omitted or nil or a positive
>   +integer, it should enable the mode.
>
> Don't you agree that it does little apart of re-shuffling the same
> words?

It also describes what happens when the argument is neither nil nor
`toggle' nor an integer. That is currently unspecified, or rather
implicitly specified by the observable (but unspecified) behavior of
`prefix-numeric-value'.

>
> > The key difference is that when called from Lisp with an
> > argument that is neither nil nor an integer, the mode is also enabled.
>
> Why would we want to require that?  This subsection describes the
> conventions, it doesn't describe the effect of certain popular
> implementation of those conventions, because we don't really want to
> _require_ modes to behave in any way beyond the described behavior.

This isn't about the implementation but the interface, i.e. the
observable behavior of minor mode functions.

>
> > "With a prefix argument ARG, enable the mode if ARG is positive, and disable it if ARG is negative or zero.
>
> This is almost exactly the same as the current:
>
>   With a prefix argument ARG, enable %s if ARG is
>   positive, and disable it otherwise.
>
> > Additionally, when called from Lisp, toggle the mode if ARG is the symbol `toggle' and interpret ARG as
> > defined by `prefix-numeric-value' otherwise."
>
> And this is exactly what I suggested back then:
>
> >  As for the doc string, please avoid repetition, it's confusing. I
> >  suggested to describe the additional features when the mode is called
> >  from Lisp by using the word "also".
>
> The wording I had in mind was similar to yours:
>
>   When called from Lisp, also enable the mode if ARG is omitted or
>   nil, and toggle it if ARG is `toggle'.

That again doesn't describe what happens if neither of these cases apply.
(My suggestion from 2017 also wouldn't work here as-is, because the
behavior of `prefix-numeric-value' isn't defined for these cases
either.)