bug#14875: 24.3.50; doc of :variable in `define-minor-mode' - lamentable

bug#14875: 24.3.50; doc of :variable in `define-minor-mode' - lamentable

[Drew Adams]

1. Both (elisp) `Defining Minor Modes' and the doc string say the same
thing, verbatim.  The manual should explain better.

2. The description/explanation is incomplete/confusing/gobbledygook, at
best.

It says that PLACE can be a "generalized variable", without giving any
explanation of what a generalized variable is, and without
cross-referencing any doc that describes such a thing.

It says that PLACE can also be a cons (GET . SET).  In this case, it
says that "SET is a function that takes one argument, the new state, and
sets it".

Huh?  It takes the NEW state as argument?  If so, where did that new state
come from?  And then it "sets" the new state?  Huh?  Does it just set it to
what it already was (the "new state" argument)?  Or does "set" here perhaps
imply setting the value to non-nil (as in setting a bit)?

It's not clear at all what the SET of (GET . SET) (1) accepts as arg,
(2) does as its main (standard) effect, or (3) returns as a value (if that
matters).

It says that if PLACE is specified as a variable then "this function
does not define a MODE variable (nor any of the terms used in :variable)".

Huh?  Does "variable" here include the "generalized variable" case?  Does
"this function" refer to the SET function of the preceding sentence?  Or
does it refer to the minor-mode function?  What on Earth does it mean for
the function (either of those functions, or whatever function is meant)
to not define "any of the terms used in :variable"?

I honestly understand almost nothing here.  :variable does not define
any of the terms used in :variable?  Huh?

Please, please.  Users deserve better.  Give us a break.  Please clear
this up.

3. And as is too often the case, the "For example,..." at the end gives
a too-trivial example that shows none of the things that someone might
really have a question about.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-07-01 on LEG570
Bzr revision: 113246 lekktu@gmail.com-20130701165437-ea20s94hqwp3ttaj
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --enable-checking CFLAGS='-O0 -g3'
 CPPFLAGS='-DGLYPH_DEBUG=1 -I/c/usr/include''