[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#36500: [External] : Re: bug#36500: 26.2; Minor mode doc strings - sa
From: |
Drew Adams |
Subject: |
bug#36500: [External] : Re: bug#36500: 26.2; Minor mode doc strings - say what the current mode-variable value is |
Date: |
Tue, 22 Jun 2021 15:10:03 +0000 |
> > `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).