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.