bug#44341: 27.1; define-minor-mode generates inaccurate docstring

[Stefan Monnier <monnier@iro.umontreal.ca>]

> (mapcar
>   (lambda (x) (test-mode x) (cons x test-mode))
>   '(t ; Should disable.

An argument of the form t has traditionally enabled the mode.
Many .emacs file have calls like (foo-mode t), so we need to preserve this.

>     nil ; Should disable

The argument nil should definitely enable the mode.

>     -33 ; Should NOT disable (but will)
>     33 ; Should enable

Negative and positive are the "canonical" way to disable and enable
a mode, no -33 should disable and 33 should enable.

>     0 ; Should disable

Historically, 0 has been defined to disable the mode, indeed.
I recommend to use -1 instead, but a lot of code uses 0.

>     toggle ; Should toggle, and will.
>     toggle ; Repeated for confirmation

Right.

>     disable ; Should disable (as a random symbol)
>     disable ; Again
>     "What?" ; Same.

These should be considered as errors.  Whether we catch them and signal
an error or silently do something else is not particular important
to me.  But we shouldn't document the behavior for those arguments as
being anything else than errors.


        Stefan