GNU bug report logs - #41026
Improve documentation of `makunbound' and `fmakunbound'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 41026 in the body.
You can then email your comments to 41026 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 2 May 2020 15:53:37 +0200

[Message part 1 (text/plain, inline)]

Severity: wishlist

Any objections to or comments on the attached patch?  Thanks.

Best regards,
Stefan Kangas

[0001-Improve-doc-strings-of-makunbound-and-fmakunbound.patch (text/x-patch, attachment)]

Message #8 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 17:03:16 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 2 May 2020 15:53:37 +0200
> 
>  DEFUN ("makunbound", Fmakunbound, Smakunbound, 1, 1, 0,
> -       doc: /* Make SYMBOL's value be void.
> -Return SYMBOL.  */)
> +       doc: /* Make variable SYMBOL's value be void.
> +Return SYMBOL.
> +
> +For more information, see Info node `(elisp) Void Variables'.
> +
> +The corresponding operation for functions is `fmakunbound'.  */)
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The "corresponding" part isn't accurate, is it?

Thanks.

Message #11 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 16:17:04 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Stefan Kangas <stefan <at> marxist.se>
>> Date: Sat, 2 May 2020 15:53:37 +0200
>> 
>>  DEFUN ("makunbound", Fmakunbound, Smakunbound, 1, 1, 0,
>> -       doc: /* Make SYMBOL's value be void.
>> -Return SYMBOL.  */)
>> +       doc: /* Make variable SYMBOL's value be void.
>> +Return SYMBOL.
>> +
>> +For more information, see Info node `(elisp) Void Variables'.
>> +
>> +The corresponding operation for functions is `fmakunbound'.  */)
>    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> The "corresponding" part isn't accurate, is it?

Sorry, I thought it was.  But my understanding of this is probably
much too naive.

Would we avoid the inaccuracy by deleting the word "corresponding"?

Thank you for reviewing.

Best regards,
Stefan Kangas

Message #14 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 17:22:39 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: 41026 <at> debbugs.gnu.org
> Date: Sat, 02 May 2020 16:17:04 +0200
> 
> >> +The corresponding operation for functions is `fmakunbound'.  */)
> >    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > The "corresponding" part isn't accurate, is it?
> 
> Sorry, I thought it was.  But my understanding of this is probably
> much too naive.
> 
> Would we avoid the inaccuracy by deleting the word "corresponding"?

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?

Message #17 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 16:55:09 +0200

On Mai 02 2020, Stefan Kangas wrote:

> +       doc: /* Make variable SYMBOL's value be void.

What's a variable symbol?  Is that the same as a varying symbol?

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Message #20 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 17:00:02 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

> On Mai 02 2020, Stefan Kangas wrote:
>
>> +       doc: /* Make variable SYMBOL's value be void.
>
> What's a variable symbol?  Is that the same as a varying symbol?

The sentence is a bit unwieldy to get right, if you also want to
include the word "variable".  Is this clearer?

"Make the value of the variable named SYMBOL be void."

Best regards,
Stefan Kangas

Message #23 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 18:41:15 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 02 May 2020 17:00:02 +0200
> Cc: 41026 <at> debbugs.gnu.org
> 
> Andreas Schwab <schwab <at> linux-m68k.org> writes:
> 
> > On Mai 02 2020, Stefan Kangas wrote:
> >
> >> +       doc: /* Make variable SYMBOL's value be void.
> >
> > What's a variable symbol?  Is that the same as a varying symbol?
> 
> The sentence is a bit unwieldy to get right, if you also want to
> include the word "variable".  Is this clearer?
> 
> "Make the value of the variable named SYMBOL be void."

I think the ELisp manual gets it right:

  Empty out the value cell of SYMBOL, making it void as a variable.

Message #26 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Andreas Schwab <schwab <at> linux-m68k.org>, Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org
Subject: RE: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 2 May 2020 13:22:28 -0700 (PDT)

> > +       doc: /* Make variable SYMBOL's value be void.
> 
> What's a variable symbol?  Is that the same as a varying symbol?

Make SYMBOL's value as a variable be void.
or
Make SYMBOL's `symbol-value' be void.

Message #29 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 22:25:57 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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?

[0001-Improve-doc-strings-of-makunbound-and-fmakunbound.patch (text/x-diff, inline)]

From bdd0f8bc5dbcb74fb7f61b786c9fd0e2c2468d80 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> 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

[Message part 3 (text/plain, inline)]

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

Message #32 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 23:12:15 +0200

Why do these unimportant functions that almost nobody needs require such
elaborate doc strings?

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Message #35 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 23:30:55 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

> Why do these unimportant functions that almost nobody needs require such
> elaborate doc strings?

I don't think I follow.  What is your objection?

Best regards,
Stefan Kangas

Message #38 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 41026 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sat, 02 May 2020 23:43:28 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > +       doc: /* Make variable SYMBOL's value be void.

  > What's a variable symbol?

That is a grammatical misparsing.
That sentence does not talk about a "variable symbol".
It talks about a variable, and SYMBOL stands for that variable.
It is like  "the buffer BUF".

Would it be clearer to say "Make the variable VAR's value be void"
and call the argument 'var'?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #41 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sun, 03 May 2020 17:21:14 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: 41026 <at> debbugs.gnu.org
> Date: Sat, 02 May 2020 22:25:57 +0200
> 
> Thanks.  Based on your feedback, this is what I came up with. WDYT?

LGTM, thanks.

> 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."?

I think it just said what it did in a confusing way.

Message #44 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41026 <at> debbugs.gnu.org
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sun, 03 May 2020 22:07:58 +0200

close 41026 27.1
thanks

Eli Zaretskii <eliz <at> gnu.org> writes:

> LGTM, thanks.

Thanks, pushed to emacs-27 as commit f9fa726ced.

Best regards,
Stefan Kangas

Message #49 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 41026 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Sun, 03 May 2020 23:06:39 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Why do these unimportant functions that almost nobody needs require such
  > elaborate doc strings?

So that those people who may want to use them, even if they are few,
can be sure of how to use them.

The cost of writing full and clear doc strings is some work, but once
that work is done, it costs nothing to have them in the source files.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #52 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Richard Stallman <rms <at> gnu.org>
Cc: 41026 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Mon, 04 May 2020 09:31:22 +0200

On Mai 03 2020, Richard Stallman wrote:

> So that those people who may want to use them, even if they are few,
> can be sure of how to use them.

They are even documented in the manual.  What makes them so special?

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Message #55 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 41026 <at> debbugs.gnu.org, Richard Stallman <rms <at> gnu.org>
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Mon, 04 May 2020 14:52:37 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

> On Mai 03 2020, Richard Stallman wrote:
>
>> So that those people who may want to use them, even if they are few,
>> can be sure of how to use them.
>
> They are even documented in the manual.  What makes them so special?

They are occasionally useful.  I'm not sure that makes them special.

But again, I'm not sure what you are saying.  Are you proposing to
remove them from the ELisp manual?

Best regards,
Stefan Kangas

Message #58 received at 41026 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41026 <at> debbugs.gnu.org, Richard Stallman <rms <at> gnu.org>
Subject: Re: bug#41026: Improve documentation of `makunbound' and `fmakunbound'
Date: Mon, 04 May 2020 15:05:25 +0200

On Mai 04 2020, Stefan Kangas wrote:

> They are occasionally useful.  I'm not sure that makes them special.

There are many functions that are occasionally useful.  Why do these two
need special care?

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.