GNU bug report logs - #38205
Unhelpful documentation for add-variable-watcher.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 38205 in the body.
You can then email your comments to 38205 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Alan Mackenzie <acm <at> muc.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Unhelpful documentation for add-variable-watcher.
Date: Thu, 14 Nov 2019 07:38:35 +0000

Hello, Emacs.

The doc string for add-variable-watcher wrongly states:

    Cause WATCH-FUNCTION to be called when SYMBOL is set.

.  Correct would be either

    Cause WATCH-FUNCTION to be called just before SYMBOL is set.

or

    Cause WATCH-FUNCTION to be called just after SYMBOL is set.

.  I'm guessing that the first of these applies, but I shouldn't have to
guess.  The difference is whether one can get the old value from SYMBOL
or not.

The documentation in the Elisp manual is similarly ambiguous.  It uses
the conjunction "whenever".

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #10 received at 38205-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 38205-done <at> debbugs.gnu.org
Subject: Re: bug#38205: Unhelpful documentation for add-variable-watcher.
Date: Fri, 15 Nov 2019 11:21:29 +0200

> Date: Thu, 14 Nov 2019 07:38:35 +0000
> From: Alan Mackenzie <acm <at> muc.de>
> 
> The doc string for add-variable-watcher wrongly states:
> 
>     Cause WATCH-FUNCTION to be called when SYMBOL is set.
> 
> .  Correct would be either
> 
>     Cause WATCH-FUNCTION to be called just before SYMBOL is set.
> 
> or
> 
>     Cause WATCH-FUNCTION to be called just after SYMBOL is set.

Well, the doc string goes on to say

  NEWVAL is the value it will be changed to.
                         ^^^^^^^
which is a clear hint to what actually happens.  But I made this even
more clear in the doc string, thanks.

> The documentation in the Elisp manual is similarly ambiguous.  It uses
> the conjunction "whenever".

Fixed that as well.

Message #13 received at 38205-done <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38205-done <at> debbugs.gnu.org
Subject: Re: bug#38205: Unhelpful documentation for add-variable-watcher.
Date: Sat, 16 Nov 2019 12:35:57 +0000

Hello, Eli.

On Fri, Nov 15, 2019 at 11:21:29 +0200, Eli Zaretskii wrote:
> > Date: Thu, 14 Nov 2019 07:38:35 +0000
> > From: Alan Mackenzie <acm <at> muc.de>

> > The doc string for add-variable-watcher wrongly states:

> >     Cause WATCH-FUNCTION to be called when SYMBOL is set.

> > .  Correct would be either

> >     Cause WATCH-FUNCTION to be called just before SYMBOL is set.

> > or

> >     Cause WATCH-FUNCTION to be called just after SYMBOL is set.

> Well, the doc string goes on to say

>   NEWVAL is the value it will be changed to.
>                          ^^^^^^^
> which is a clear hint to what actually happens.  But I made this even
> more clear in the doc string, thanks.

> > The documentation in the Elisp manual is similarly ambiguous.  It uses
> > the conjunction "whenever".

> Fixed that as well.

Thanks!

-- 
Alan Mackenzie (Nuremberg, Germany).

Previous Next

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