Commit 0114bb96 authored by Eli Zaretskii's avatar Eli Zaretskii

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)
parent 3495cefc
Pipeline #4055 failed with stage
in 90 minutes and 2 seconds
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment