bug#41026: Improve documentation of `makunbound' and `fmakunbound'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I'd just say "See also `fmakunbound'".  And the same in the
> fmakunbound doc string.
>
> Btw, why the link to the manual?  Does the manual say something
> important that the doc strings don't?  If it does, perhaps we should
> make the laconic doc string slightly more elaborate?

Thanks.  Based on your feedback, this is what I came up with. WDYT?

>From bdd0f8bc5dbcb74fb7f61b786c9fd0e2c2468d80 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 2 May 2020 15:51:31 +0200
Subject: [PATCH] Improve doc strings of makunbound and fmakunbound

* src/data.c (Fmakunbound, Ffmakunbound): Improve doc
strings.  (Bug#41026)
---
 src/data.c | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/src/data.c b/src/data.c
index bce2e53cfb..1db0a983b4 100644
--- a/src/data.c
+++ b/src/data.c
@@ -695,8 +695,14 @@ DEFUN ("fboundp", Ffboundp, Sfboundp, 1, 1, 0,
 }
 
 DEFUN ("makunbound", Fmakunbound, Smakunbound, 1, 1, 0,
-       doc: /* Make SYMBOL's value be void.
-Return SYMBOL.  */)
+       doc: /* Empty out the value cell of SYMBOL, making it void as a 
variable.
+Return SYMBOL.
+
+If a variable is void, trying to evaluate the variable signals a
+`void-variable' error, instead of returning a value.  For more
+details, see Info node `(elisp) Void Variables'.
+
+See also `fmakunbound'.  */)
   (register Lisp_Object symbol)
 {
   CHECK_SYMBOL (symbol);
@@ -707,8 +713,14 @@ DEFUN ("makunbound", Fmakunbound, Smakunbound, 1, 1, 0,
 }
 
 DEFUN ("fmakunbound", Ffmakunbound, Sfmakunbound, 1, 1, 0,
-       doc: /* Make SYMBOL's function definition be nil.
-Return SYMBOL.  */)
+       doc: /* Make SYMBOL's function definition be void.
+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'.
+
+See also `makunbound'.  */)
   (register Lisp_Object symbol)
 {
   CHECK_SYMBOL (symbol);
-- 
2.26.2

BTW, according to (elisp) Function Cells:

     Note that void is not the same as ‘nil’ or the symbol ‘void’.  The
  symbols ‘nil’ and ‘void’ are Lisp objects, and can be stored into a
  function cell just as any other object can be (and they can be valid
  functions if you define them in turn with ‘defun’).  A void function
  cell contains no object whatsoever.

So I suppose that means that the old `fmakunbound' docstring was
incorrect in saying: "Make SYMBOL's function definition be nil."?

Best regards,
Stefan Kangas