bug#21709: 25.0.50; doc of :variable in `define-minor-mode'

[Lars Ingebrigtsen <larsi@gnus.org>]

Drew Adams <drew.adams@oracle.com> writes:

> The doc is unclear - both the doc string and (elisp) `Defining Minor
> Modes'.  Specifically, the part about PLACE being (GET . SET).
>
>  PLACE can also be of the form (GET . SET), where GET is
>  an expression that returns the current state, and SET is
>  a function that takes one argument, the new state, and
>  sets it.
>
>  PLACE can also be a cons '(GET . SET)', where GET is an expression that
>  returns the current state, and SET is a function of one argument (a
>  state) that sets it.
>
> Surely the function does not "set" a "state".  It might set the
> variable to a new value (but it does not "set" the value).
>
> What is the function argument?  A "state"?  What does that mean?
> State of what?  What form does this "state" take?  What does it do?
>
> My guess is that the doc should says something like this:
>
>  The argument is the new variable value, which is assigned to PLACE.
>
> Presumably, "state" should be replaced by "value" everywhere, here.
> But that's just a guess.

I think "state" is fine in this context, but you're right that this can
be improved.  I've altered both the doc string and the manual so be more
along your suggested "which is assigned to PLACE".

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