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

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 111 bytes --]

Severity: wishlist

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

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Improve-doc-strings-of-makunbound-and-fmakunbound.patch --]
[-- Type: text/x-patch, Size: 1379 bytes --]

From f1cab1061f02cb88c9e63a67935e9701cee3781d 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.
---
 src/data.c | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/data.c b/src/data.c
index bce2e53cfb..e7b9e74a30 100644
--- a/src/data.c
+++ b/src/data.c
@@ -695,8 +695,12 @@ DEFUN ("fboundp", Ffboundp, Sfboundp, 1, 1, 0,
 }
 
 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'.  */)
   (register Lisp_Object symbol)
 {
   CHECK_SYMBOL (symbol);
@@ -708,7 +712,11 @@ DEFUN ("makunbound", Fmakunbound, Smakunbound, 1, 1, 0,
 
 DEFUN ("fmakunbound", Ffmakunbound, Sfmakunbound, 1, 1, 0,
        doc: /* Make SYMBOL's function definition be nil.
-Return SYMBOL.  */)
+Return SYMBOL.
+
+For more information, see Info node `(elisp) Function Cells'.
+
+The corresponding operation for variables is `makunbound'.  */)
   (register Lisp_Object symbol)
 {
   CHECK_SYMBOL (symbol);
-- 
2.26.2

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@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.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefan@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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 41026@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?

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

[Andreas Schwab]

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@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

[Stefan Kangas]

Andreas Schwab <schwab@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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 02 May 2020 17:00:02 +0200
> Cc: 41026@debbugs.gnu.org
> 
> Andreas Schwab <schwab@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.

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

[Drew Adams]

> > +       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.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 390 bytes --]

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?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-doc-strings-of-makunbound-and-fmakunbound.patch --]
[-- Type: text/x-diff, Size: 1641 bytes --]

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


[-- Attachment #3: Type: text/plain, Size: 561 bytes --]


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

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

[Andreas Schwab]

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

Andreas.

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

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

[Stefan Kangas]

Andreas Schwab <schwab@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

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

[Richard Stallman]

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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 41026@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.

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

[Stefan Kangas]

close 41026 27.1
thanks

Eli Zaretskii <eliz@gnu.org> writes:

> LGTM, thanks.

Thanks, pushed to emacs-27 as commit f9fa726ced.

Best regards,
Stefan Kangas

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

[Richard Stallman]

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

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

[Andreas Schwab]

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@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

[Stefan Kangas]

Andreas Schwab <schwab@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

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

[Andreas Schwab]

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@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."