From 0114bb964afd81b6a6dc8c742bceba61d0f2a7dc Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 15 Nov 2019 11:16:09 +0200 Subject: [PATCH] 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 f92540dbd36..f7fe738ac30 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 9efcd72f93e..26e8611304b 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 -- 2.39.5