From: Eli Zaretskii <eliz@gnu.org>
Date: Sun, 27 Oct 2024 11:16:36 +0000 (+0200)
Subject: Update the documentation of void functions
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=33907dc26a07ad140d180fd19f0afd6dacfeb465;p=emacs.git

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)
---

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);