master 0114bb9: Improve documentation of 'add-variable-watcher'

[Eli Zaretskii]

branch: master
commit 0114bb964afd81b6a6dc8c742bceba61d0f2a7dc
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of 'add-variable-watcher'
    
    * doc/lispref/variables.texi (Watching Variables): Clarify the
    documentation of 'add-variable-watcher' and fix markup.
    
    * src/data.c (Fadd_variable_watcher): Clarify the doc string.
    (Bug#38205)
---
 doc/lispref/variables.texi | 28 +++++++++++++++-------------
 src/data.c                 |  5 +++--
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index f92540d..f7fe738 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -832,10 +832,10 @@ error is signaled.
 @cindex watchpoints for Lisp variables
 
 It is sometimes useful to take some action when a variable changes its
-value.  The watchpoint facility provides the means to do so.  Some
-possible uses for this feature include keeping display in sync with
-variable settings, and invoking the debugger to track down unexpected
-changes to variables (@pxref{Variable Debugging}).
+value.  The @dfn{variable watchpoint} facility provides the means to
+do so.  Some possible uses for this feature include keeping display in
+sync with variable settings, and invoking the debugger to track down
+unexpected changes to variables (@pxref{Variable Debugging}).
 
 The following functions may be used to manipulate and query the watch
 functions for a variable.
@@ -845,15 +845,17 @@ This function arranges for @var{watch-function} to be 
called whenever
 @var{symbol} is modified.  Modifications through aliases
 (@pxref{Variable Aliases}) will have the same effect.
 
-@var{watch-function} will be called with 4 arguments: (@var{symbol}
-@var{newval} @var{operation} @var{where}).
-
-@var{symbol} is the variable being changed.
-@var{newval} is the value it will be changed to.
-@var{operation} is a symbol representing the kind of change, one of:
-`set', `let', `unlet', `makunbound', and `defvaralias'.
-@var{where} is a buffer if the buffer-local value of the variable is
-being changed, @code{nil} otherwise.
+@var{watch-function} will be called, just before changing the value of
+@var{symbol}, with 4 arguments: @var{symbol}, @var{newval},
+@var{operation}, and @var{where}.
+@var{symbol} is the variable being changed.  @var{newval} is the value
+it will be changed to.  (The old value is available to
+@var{watch-function} as the value of @var{symbol}, since it was not
+yet changed to @var{newval}.)  @var{operation} is a symbol
+representing the kind of change, one of: @code{set}, @code{let},
+@code{unlet}, @code{makunbound}, or @code{defvaralias}.  @var{where}
+is a buffer if the buffer-local value of the variable is being
+changed, @code{nil} otherwise.
 @end defun
 
 @defun remove-variable-watch symbol watch-function
diff --git a/src/data.c b/src/data.c
index 9efcd72..26e8611 100644
--- a/src/data.c
+++ b/src/data.c
@@ -1472,11 +1472,12 @@ harmonize_variable_watchers (Lisp_Object alias, 
Lisp_Object base_variable)
 
 DEFUN ("add-variable-watcher", Fadd_variable_watcher, Sadd_variable_watcher,
        2, 2, 0,
-       doc: /* Cause WATCH-FUNCTION to be called when SYMBOL is set.
+       doc: /* Cause WATCH-FUNCTION to be called when SYMBOL is about to be 
set.
 
 It will be called with 4 arguments: (SYMBOL NEWVAL OPERATION WHERE).
 SYMBOL is the variable being changed.
-NEWVAL is the value it will be changed to.
+NEWVAL is the value it will be changed to.  (The variable still has
+the old value when WATCH-FUNCTION is called.)
 OPERATION is a symbol representing the kind of change, one of: `set',
 `let', `unlet', `makunbound', and `defvaralias'.
 WHERE is a buffer if the buffer-local value of the variable is being