Subject: bug#38205: closed (Re: bug#38205: Unhelpful documentation for add-variable-watcher.)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 15 Nov 2019 09:22:02 +0000

Your bug report

#38205: Unhelpful documentation for add-variable-watcher.

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
38205: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=38205
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#38205: Unhelpful documentation for add-variable-watcher.
From: Eli Zaretskii <[email-masked]>
To: Alan Mackenzie <[email-masked]>
Cc: [email-masked]
Date: Fri, 15 Nov 2019 11:21:29 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Thu, 14 Nov 2019 07:38:35 +0000
> From: Alan Mackenzie <[email-masked]>
> 
> 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.

Subject: Unhelpful documentation for add-variable-watcher.
From: Alan Mackenzie <[email-masked]>
To: [email-masked]
Date: Thu, 14 Nov 2019 07:38:35 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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).