From 33907dc26a07ad140d180fd19f0afd6dacfeb465 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 27 Oct 2024 13:16:36 +0200 Subject: [PATCH] Update the documentation of void functions * doc/lispref/functions.texi (Function Cells): * src/data.c (Ffboundp, Ffmakunbound, Fsymbol_function): Update documentation to the changes of how void functions are represented since Emacs 24.5. (Bug#73886) (cherry picked from commit b0aaee93fde245b972a0d69b60328550f53bc043) --- doc/lispref/functions.texi | 24 ++++++++++++------------ src/data.c | 12 ++++++------ 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index ef3e665f9f2..db2c4197144 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1511,9 +1511,9 @@ indirect-function}. This returns the object in the function cell of @var{symbol}. It does not check that the returned object is a legitimate function. -If the function cell is void, the return value is @code{nil}. To -distinguish between a function cell that is void and one set to -@code{nil}, use @code{fboundp} (see below). +If the function cell is void, the return value is @code{nil}. It is +impossible to distinguish between a function cell that is void and one +set to @code{nil}. @example @group @@ -1538,24 +1538,24 @@ that that symbol's function cell is @dfn{void}. In other words, the function cell does not have any Lisp object in it. If you try to call the symbol as a function, Emacs signals a @code{void-function} error. - Note that void is not the same as @code{nil} or the symbol -@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, -and can be stored into a function cell just as any other object can be -(and @code{void} can be a valid function if you define it with -@code{defun}). A void function cell contains no object whatsoever. + Unlike with void variables (@pxref{Void Variables}), a symbol's +function cell that contains @code{nil} is indistinguishable from the +function's being void. Note that void is not the same as the symbol +@code{void}: @code{void} can be a valid function if you define it with +@code{defun}. You can test the voidness of a symbol's function definition with @code{fboundp}. After you have given a symbol a function definition, you can make it void once more using @code{fmakunbound}. @defun fboundp symbol -This function returns @code{t} if the symbol has an object in its -function cell, @code{nil} otherwise. It does not check that the object -is a legitimate function. +This function returns @code{t} if the symbol has a non-@code{nil} object +in its function cell, @code{nil} otherwise. It does not check that the +object is a legitimate function. @end defun @defun fmakunbound symbol -This function makes @var{symbol}'s function cell void, so that a +This function makes @var{symbol}'s function cell @code{nil}, so that a subsequent attempt to access this cell will cause a @code{void-function} error. It returns @var{symbol}. (See also @code{makunbound}, in @ref{Void Variables}.) diff --git a/src/data.c b/src/data.c index fd2d9705642..73dd2f5d4ed 100644 --- a/src/data.c +++ b/src/data.c @@ -756,7 +756,7 @@ global value outside of any lexical scope. */) breaking backward compatibility, as some users of fboundp may expect t in particular, rather than any true value. */ DEFUN ("fboundp", Ffboundp, Sfboundp, 1, 1, 0, - doc: /* Return t if SYMBOL's function definition is not void. */) + doc: /* Return t if SYMBOL's function definition is neither void nor nil. */) (Lisp_Object symbol) { CHECK_SYMBOL (symbol); @@ -782,12 +782,12 @@ See also `fmakunbound'. */) } DEFUN ("fmakunbound", Ffmakunbound, Sfmakunbound, 1, 1, 0, - doc: /* Make SYMBOL's function definition be void. + doc: /* Make SYMBOL's function definition be nil. Return SYMBOL. -If a function definition is void, trying to call a function by that -name will cause a `void-function' error. For more details, see Info -node `(elisp) Function Cells'. +If a function definition is nil or void, trying to call a function by +that name will cause a `void-function' error. For more details, see +Info node `(elisp) Function Cells'. See also `makunbound'. */) (register Lisp_Object symbol) @@ -800,7 +800,7 @@ See also `makunbound'. */) } DEFUN ("symbol-function", Fsymbol_function, Ssymbol_function, 1, 1, 0, - doc: /* Return SYMBOL's function definition, or nil if that is void. */) + doc: /* Return SYMBOL's function definition, or nil if that is void or nil. */) (Lisp_Object symbol) { CHECK_SYMBOL (symbol); -- 2.39.2