bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is

[Lars Ingebrigtsen <larsi@gnus.org>]

Drew Adams <drew.adams@oracle.com> writes:

> `define-minor-mode' do the following (or at least some of it):
>
> 1. Mention the mode variable (typically the same name as the mode,
>    but in any case the name is known to `define-minor-mode').
>    (The doc string currently mentions the keymap, but not the var.)

I've now done this in Emacs 28.

> 2. Show the current value of the variable, just as we do for the keymap.
>    If undefined so far then say so, just as we do for the keymap.

I think that would be pretty odd -- it's just a function doc string,
and the value of these variables in the *Help* buffer is usually nil.

> 3. Say whether the variable is global (an option, customizable), or
>    buffer-local.

For minor modes?  No, I think that would be counter-productive -- minor
modes should be toggled with the minor mode command.

And besides -- the "mode variable" isn't necessarily a variable: You can
use a general setf-able thing for it.  And the getter and the setter
aren't the same.  The useful thing, I think, is to have the doc string
document the getter "variable", so that you know how to check whether
the mode is off or on.  (Which I've now done, so I'm closing this bug
report.)

> 4. Maybe mention that the variable is set/reset automatically when you
>    toggle the mode.  If the var is global mention that you can set/reset
>    it manually using Customize.

Ditto.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no