Docstrings of minor modes are unclear

[Tassilo Horn <tsdh@gnu.org>]

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