bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands

[Drew Adams]

The doc needs improvement when describing calling the mode from Lisp.

1. The doc string of `define-minor-mode' says this:

     When called from Lisp, the mode command toggles the mode if the
     argument is `toggle', disables the mode if the argument is a
     non-positive integer, and enables the mode otherwise (including if
     the argument is omitted or nil or a positive integer).

   This is wrong (incomplete).  It disables the mode if the
   `prefix-numeric-value' of ARG <= 0, not if ARG is a non-positive
   integer.  The code does this: (prefix-numeric-value arg).  So if you
   pass the symbol `-' as ARG then the mode is disabled.

1. The (default) doc string produced by `define-minor-mode' says this:

     If called from Lisp, enable the mode if ARG is omitted or nil, and
     toggle it if ARG is `toggle'.

   Again, this is wrong (incomplete).  It doesn't say that if ARG is
   non-nil other than `toggle' then disable the mode if the
   `prefix-numeric-value' of ARG <= 0, and enable it if the
   `prefix-numeric-value' of ARG > 0.

3. The Elisp manual doc says this (node `Defining Minor Modes'):

     From Lisp, an argument of 'toggle' toggles the mode, whereas an
     omitted or 'nil' argument enables the mode.

   Again, this is wrong (incomplete).

   * It says nothing about how the mode is disabled when called from
     Lisp.  It should say that an ARG whose `prefix-numeric-value' is
     non-positive disables the mode.

   * It should say that an ARG whose `prefix-numeric-value' is
     non-positive enables the mode.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''