Docstrings of minor modes are unclear

Docstrings of minor modes are unclear

[Tassilo Horn]

Hi all,

the docstrings of (global) minor modes defined with `define-minor-mode'
and `define-globalized-minor-mode' are a bit unclear.  Both say:

  If called from Lisp, enable the mode if ARG is omitted or nil.

This is only halfway true.  The minor more will be activated if ARG is
omitted or if ARG is not a negative integer or zero.

I've now seen that in the meantime the docstring generated by
`define-minor-mode' has been made a bit accurate in terms of mentioning
'toggle, but it's still not clear.

Any objections to the following patch?


--8<---------------cut here---------------start------------->8---
=== modified file 'lisp/emacs-lisp/easy-mmode.el'
--- lisp/emacs-lisp/easy-mmode.el	2012-09-22 15:24:26 +0000
+++ lisp/emacs-lisp/easy-mmode.el	2012-10-12 08:42:31 +0000
@@ -259,8 +259,11 @@
 	 ,(or doc
 	      (format (concat "Toggle %s on or off.
 With a prefix argument ARG, enable %s if ARG is
-positive, and disable it otherwise.  If called from Lisp, enable
-the mode if ARG is omitted or nil, and toggle it if ARG is `toggle'.
+positive, and disable it otherwise.  When called from Lisp,
+toggle the mode if the argument is `toggle', disable the mode if
+the argument is a non-positive integer, and enable the mode
+otherwise including if the argument is omitted or nil or a
+positive integer.
 \\{%s}") pretty-name pretty-name keymap-sym))
 	 ;; Use `toggle' rather than (if ,mode 0 1) so that using
 	 ;; repeat-command still does the toggling correctly.
@@ -381,8 +384,10 @@
 	 ;; doc string.
 	 ,(format "Toggle %s in all buffers.
 With prefix ARG, enable %s if ARG is positive;
-otherwise, disable it.  If called from Lisp, enable the mode if
-ARG is omitted or nil.
+otherwise, disable it.  If called from Lisp, toggle the mode if
+the argument is `toggle', disable the mode if the argument is a
+non-positive integer, and enable the mode otherwise including if
+the argument is omitted or nil or a positive integer.
 
 %s is enabled in all buffers where
 \`%s' would do it.
--8<---------------cut here---------------end--------------->8---

Bye,
Tassilo

Re: Docstrings of minor modes are unclear

[Stefan Monnier]

> the docstrings of (global) minor modes defined with `define-minor-mode'
> and `define-globalized-minor-mode' are a bit unclear.  Both say:

>   If called from Lisp, enable the mode if ARG is omitted or nil.

> This is only halfway true.

> I've now seen that in the meantime the docstring generated by
> `define-minor-mode' has been made a bit accurate in terms of mentioning
> 'toggle, but it's still not clear.

> Any objections to the following patch?

This ends up duplicating the description (once for the interactive case
and once for the Lisp call case).  I'd rather keep something short, like
we have.
We just need to reword it a bit so as to make it clear that when we say
"If called from Lisp," it doesn't mean that what was said before doesn't
apply, but that *in addition* to what was said before "enable the mode
if ARG is omitted or nil, and toggle it if ARG is `toggle'".

I don't have a good suggestion for how to do that, tho.


        Stefan