Re: `define-minor-mode' makes erroneous docstrings.

[Luc Teirlinck <teirllm@dms.auburn.edu>]

Stefan Monnier wrote:

   The comment about not setting the variable locally should not be added if
   the mode is not declared to be global.

If the mode is not global, the comment is less explicit, but still says:

   Use the command `visible-mode' to change this variable.

In the case of Visible mode, this is actually correct: just setting
the variable does not work.

Whether or not setting the variable works does not depend on whether
the mode is global or local.  The only difference is that for local
modes, setting through Custom does not work.

Maybe if the minor mode defined using `define-minor-mode', local or
global, has an empty explicitly specified function definition, the
docstring could explicitly say that setting the variable has the same
effect as calling the function, except for some side stuff, like
running the mode hooks.

Examples include line-number-mode, column-number-mode, size-indication-mode
and transient-mark-mode.  I guess that there must be many others.

There is the problem of reconciling stuff in `(emacs)Minor Modes' with
the behavior of `define-minor-mode'.  Part of that might be updating
the node, but part of it might be correcting misfeatures of
`define-minor-mode'.

Sincerely,

Luc.