bug#10909: 24.0.94; doc of `define-minor-mode'

["Drew Adams" <drew.adams@oracle.com>]

> >> IOW, it says nothing about what happens when an arg is 
> >> passed that is not nil or omitted or `toggle'.
> >> And I've seen at least one user try to use `(foo-mode t)'.
> >> It turns out that that has the same effect as `(foo-mode 1)',
> >> but nothing in the doc says that it should.
> >
> > Fixed in trunk.
> 
> Actually, I think the right fix is to replace calls that use t with
> calls that use 1, rather than documenting the accidental behavior.

I don't know exactly what the fix was.  (The latest build I have is 
GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600) of 2012-09-17 on MARVIN.)

But I think perhaps you are missing the point.

The doc says nothing about ANY non-nil value other than `toggle'.  It thus says
NOTHING about how to turn OFF the mode using Lisp.  It also does not say that 1
or 42 or t or `stefan' turns the mode on.  (In particular, it does not favor 1
or 42 over t.)

At the very least the doc should say that a positive arg turns it on and a
non-positive value turns it off.

That's the point.  The doc is OK wrt interactive use, but not wrt Lisp calls.
It's not about t vs 1 in any existing Lisp code.  It's about saying what the
possible argument values do.

Presumably, most users calling `define-minor-mode' will mention in the doc of
their new mode command how to call it from Lisp, since some users of their mode,
especially if it is global, will prefer to turn it on in their init files.

That is, presumably most users of `define-minor-mode' will NOT just document
their new mode following the example given in the manual: "If enabled, foo on
you!".  They will hopefully document it in a way that tells users how to turn
the mode on and off, both interactively and using Lisp.  (That part could be,
but is not, done automatically by `define-minor-mode'.)

To document that behavior for their users, users of `define-minor-mode' should
have access to doc for the macro that tells them how users of their new modes
can turn them on and off using Lisp.  It's really the least they can expect from
a general utility macro.