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

Previous Next

Full log

Message #16 received at 21709 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21709 <at> debbugs.gnu.org
Subject: Re: bug#21709: 25.0.50; doc of :variable in `define-minor-mode'
Date: Mon, 16 Aug 2021 14:22:58 +0200

Drew Adams <drew.adams <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.