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

[Drew Adams <drew.adams@oracle.com>]

> > `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.

Why do you think it would be odd?  It would be helpful.
The value reported would of course be for the buffer
where help was invoked - not for `*Help*' (unless it
was invoked there).

That's the way `*Help*' works and has always worked.
`C-h k <whatever>' doesn't tell you the binding in
`*Help*'.  I'm surprised to see this kind of argument
for not documenting something.

> > 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.

Regardless of your last phrase, which is true in general
(but not always), a globalized minor mode DOES create
a user option - customizable.  Ask yourself why.  Help
should tell users about it when that's the case.

Users shouldn't have to consult the doc for
`define-minor-mode' and `define-globalized-minor-mode'
each time they ask for help on a minor mode.  That's
been the problem from the outset, and it's still a
problem to some extent.

> And besides -- the "mode variable" isn't necessarily a variable:

No, not necessarily.  All the more reason for Help to
tell you what it is.  It should tell you when it's a
user option, a normal defvar, and a generalized var.

> The useful thing, I think, is to have the doc string
> document the getter "variable", 

There is no one "useful thing".  Certainly documenting
the variable (generalized or not) is important, and
it's only one of the things that's important.

> so that you know how to check whether the mode is
> off or on.

Help on the mode should also do that - see the first
thing, above.  Knowing what the variable is is good.
Knowing what the current state is is good.  Help on
a minor mode should tell you all such things.

> so I'm closing this bug report.)

Too bad.  But at least you presumably made some of
the suggested improvements.

> > 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.

Dunno what "ditto" means here.  There was some that
you did and much that you didn't do.  Whether you
did #4 isn't clear (without digging out the new code).