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:

> Have the automatically provided part of a minor-mode doc string, from
> `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.)
>
> 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.

Here's the current output from a random minor mode defined by that
function:

---

epa-mail-mode is an autoloaded interactive compiled Lisp function in
‘epa-mail.el’.

(epa-mail-mode &optional ARG)

A minor-mode for composing encrypted/clearsigned mails.

If called interactively, enable epa-mail mode if ARG is positive, and
disable it if ARG is zero or negative.  If called from Lisp,
also enable the mode if ARG is omitted or nil, and toggle it
if ARG is ‘toggle’; disable the mode otherwise.

---

No mention of a keymap?

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

Yes, that makes sense.  Currently a number of these modes say so
themselves, so that should also be adjusted:

---

auto-insert-mode is an autoloaded interactive compiled Lisp function
in ‘autoinsert.el’.

(auto-insert-mode &optional ARG)

Toggle Auto-insert mode, a global minor mode.

[...]

---

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

Yup.

> 5. Any particularities, e.g. from using `:variable' should be taken into
>    account, so the doc string is correct for all cases.

Makes sense.

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