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)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index f92540dbd3605d05a78cafaa27310f758b0572da..f7fe738ac302a6157215493fed5e69c46a5e7d44 100644 (file)
--- 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 9efcd72f93edab4b0ed9e118f1929a469a2e39ee..26e8611304b6e98622f1aef230ef6084ed4aee0b 100644 (file)
--- 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