bug#55562: 28.1.50; Wrong hash table return values in Elisp manual

bug#55562: 28.1.50; Wrong hash table return values in Elisp manual

[Basil L. Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Severity: minor
Tags: patch

0. emacs -Q
1. C-h f clrhash RET

> Clear hash table TABLE and return it.

2. C-h S clrhash RET

> Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
> TABLE.  In Emacs Lisp, it returns ‘nil’.

It seems the following changes never propagated to the manual:

(Fputhash): Return `value' rather than nil.
d9c4f922fb 2000-07-03 06:59:05 +0000
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=d9c4f922fb

* fns.c (Fputhash): Document return value.
a54e348216 2011-06-06 18:39:26 -0700
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=a54e348216

And the following change wasn't announced in etc/NEWS either:

(Fclrhash): Return TABLE.
ccd8f7fe14 2008-01-25 10:01:15 +0000
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=ccd8f7fe14

Is there any point in announcing the status quo, or can we just update
the manual, e.g. as follows?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-hash-table-function-return-values-in-manual.patch --]
[-- Type: text/x-diff, Size: 1450 bytes --]

From b63ec2658f1c8782620c7418c8282f29249333cd Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sat, 21 May 2022 23:11:33 +0300
Subject: [PATCH] Fix hash table function return values in manual

* doc/lispref/hash.texi (Hash Access): Reconcile documented return
values of puthash and clrhash with their respective docstrings.
---
 doc/lispref/hash.texi | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index a566d89824..34eda45b23 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -203,7 +203,8 @@ Hash Access
 @defun puthash key value table
 This function enters an association for @var{key} in @var{table}, with
 value @var{value}.  If @var{key} already has an association in
-@var{table}, @var{value} replaces the old associated value.
+@var{table}, @var{value} replaces the old associated value.  This
+function always returns @var{value}.
 @end defun
 
 @defun remhash key table
@@ -219,10 +220,7 @@ Hash Access
 @defun clrhash table
 This function removes all the associations from hash table @var{table},
 so that it becomes empty.  This is also called @dfn{clearing} the hash
-table.
-
-@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
-@var{table}.  In Emacs Lisp, it returns @code{nil}.
+table.  @code{clrhash} returns the empty @var{table}.
 @end defun
 
 @defun maphash function table
-- 
2.35.1


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


Thanks,

-- 
Basil

In GNU Emacs 28.1.50 (build 1, x86_64-pc-linux-gnu)
 of 2022-05-21 built on tia
Repository revision: 139bfa1a0884dbd2600fc1bd11d11f41d3f9ef94
Repository branch: wt/emacs-28-nox
System Description: Debian GNU/Linux bookworm/sid

Configured using:
 'configure CC=gcc-12 'CFLAGS=-O2 -march=native'
 --prefix=/home/blc/.local --program-suffix=-28-nox
 --with-file-notification=yes --with-x-toolkit=no --without-x'

Configured features:
ACL DBUS GMP GNUTLS GPM JSON LCMS2 LIBSELINUX LIBSYSTEMD LIBXML2 MODULES
NOTIFY INOTIFY PDUMPER SECCOMP SOUND THREADS XIM ZLIB

bug#55562: 28.1.50; Wrong hash table return values in Elisp manual

[Eli Zaretskii]

[Adding Stefan and Daniel to the CC.]

> Date: Sat, 21 May 2022 23:29:04 +0300
> From:  "Basil L. Contovounesios" via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Severity: minor
> Tags: patch
> 
> 0. emacs -Q
> 1. C-h f clrhash RET
> 
> > Clear hash table TABLE and return it.
> 
> 2. C-h S clrhash RET
> 
> > Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
> > TABLE.  In Emacs Lisp, it returns ‘nil’.
> 
> It seems the following changes never propagated to the manual:
> 
> (Fputhash): Return `value' rather than nil.
> d9c4f922fb 2000-07-03 06:59:05 +0000
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=d9c4f922fb
> 
> * fns.c (Fputhash): Document return value.
> a54e348216 2011-06-06 18:39:26 -0700
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=a54e348216
> 
> And the following change wasn't announced in etc/NEWS either:
> 
> (Fclrhash): Return TABLE.
> ccd8f7fe14 2008-01-25 10:01:15 +0000
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=ccd8f7fe14
> 
> Is there any point in announcing the status quo, or can we just update
> the manual, e.g. as follows?
> 
> 
> >From b63ec2658f1c8782620c7418c8282f29249333cd Mon Sep 17 00:00:00 2001
> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Sat, 21 May 2022 23:11:33 +0300
> Subject: [PATCH] Fix hash table function return values in manual
> 
> * doc/lispref/hash.texi (Hash Access): Reconcile documented return
> values of puthash and clrhash with their respective docstrings.
> ---
>  doc/lispref/hash.texi | 8 +++-----
>  1 file changed, 3 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
> index a566d89824..34eda45b23 100644
> --- a/doc/lispref/hash.texi
> +++ b/doc/lispref/hash.texi
> @@ -203,7 +203,8 @@ Hash Access
>  @defun puthash key value table
>  This function enters an association for @var{key} in @var{table}, with
>  value @var{value}.  If @var{key} already has an association in
> -@var{table}, @var{value} replaces the old associated value.
> +@var{table}, @var{value} replaces the old associated value.  This
> +function always returns @var{value}.
>  @end defun
>  
>  @defun remhash key table
> @@ -219,10 +220,7 @@ Hash Access
>  @defun clrhash table
>  This function removes all the associations from hash table @var{table},
>  so that it becomes empty.  This is also called @dfn{clearing} the hash
> -table.
> -
> -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
> -@var{table}.  In Emacs Lisp, it returns @code{nil}.
> +table.  @code{clrhash} returns the empty @var{table}.
>  @end defun
>  
>  @defun maphash function table
> -- 
> 2.35.1
> 
> Thanks,
> 
> -- 
> Basil
> 
> In GNU Emacs 28.1.50 (build 1, x86_64-pc-linux-gnu)
>  of 2022-05-21 built on tia
> Repository revision: 139bfa1a0884dbd2600fc1bd11d11f41d3f9ef94
> Repository branch: wt/emacs-28-nox
> System Description: Debian GNU/Linux bookworm/sid
> 
> Configured using:
>  'configure CC=gcc-12 'CFLAGS=-O2 -march=native'
>  --prefix=/home/blc/.local --program-suffix=-28-nox
>  --with-file-notification=yes --with-x-toolkit=no --without-x'
> 
> Configured features:
> ACL DBUS GMP GNUTLS GPM JSON LCMS2 LIBSELINUX LIBSYSTEMD LIBXML2 MODULES
> NOTIFY INOTIFY PDUMPER SECCOMP SOUND THREADS XIM ZLIB

bug#55562: 28.1.50; Wrong hash table return values in Elisp manual

[Basil L. Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii [2022-05-22 01:10 -0400] wrote:

> [Adding Stefan and Daniel to the CC.]
>
>> Date: Sat, 21 May 2022 23:29:04 +0300
>> From:  "Basil L. Contovounesios" via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> Severity: minor
>> Tags: patch
>> 
>> 0. emacs -Q
>> 1. C-h f clrhash RET
>> 
>> > Clear hash table TABLE and return it.
>> 
>> 2. C-h S clrhash RET
>> 
>> > Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
>> > TABLE.  In Emacs Lisp, it returns ‘nil’.
>> 
>> It seems the following changes never propagated to the manual:
>> 
>> (Fputhash): Return `value' rather than nil.
>> d9c4f922fb 2000-07-03 06:59:05 +0000
>> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=d9c4f922fb
>> 
>> * fns.c (Fputhash): Document return value.
>> a54e348216 2011-06-06 18:39:26 -0700
>> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=a54e348216
>> 
>> And the following change wasn't announced in etc/NEWS either:
>> 
>> (Fclrhash): Return TABLE.
>> ccd8f7fe14 2008-01-25 10:01:15 +0000
>> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=ccd8f7fe14
>> 
>> Is there any point in announcing the status quo, or can we just update
>> the manual, e.g. as follows?
>> 
>> >From b63ec2658f1c8782620c7418c8282f29249333cd Mon Sep 17 00:00:00 2001
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Sat, 21 May 2022 23:11:33 +0300
>> Subject: [PATCH] Fix hash table function return values in manual
>> 
>> * doc/lispref/hash.texi (Hash Access): Reconcile documented return
>> values of puthash and clrhash with their respective docstrings.
>> ---
>>  doc/lispref/hash.texi | 8 +++-----
>>  1 file changed, 3 insertions(+), 5 deletions(-)
>> 
>> diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
>> index a566d89824..34eda45b23 100644
>> --- a/doc/lispref/hash.texi
>> +++ b/doc/lispref/hash.texi
>> @@ -203,7 +203,8 @@ Hash Access
>>  @defun puthash key value table
>>  This function enters an association for @var{key} in @var{table}, with
>>  value @var{value}.  If @var{key} already has an association in
>> -@var{table}, @var{value} replaces the old associated value.
>> +@var{table}, @var{value} replaces the old associated value.  This
>> +function always returns @var{value}.
>>  @end defun
>>  
>>  @defun remhash key table
>> @@ -219,10 +220,7 @@ Hash Access
>>  @defun clrhash table
>>  This function removes all the associations from hash table @var{table},
>>  so that it becomes empty.  This is also called @dfn{clearing} the hash
>> -table.
>> -
>> -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
>> -@var{table}.  In Emacs Lisp, it returns @code{nil}.
>> +table.  @code{clrhash} returns the empty @var{table}.
>>  @end defun
>>  
>>  @defun maphash function table
>> -- 
>> 2.35.1

Is this suitable for Emacs 28?

Thanks,

-- 
Basil

bug#55562: 28.1.50; Wrong hash table return values in Elisp manual

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  Daniel Colascione
>  <dancol@dancol.org>,  55562@debbugs.gnu.org
> Date: Mon, 27 Jun 2022 23:43:59 +0300
> 
> Is this suitable for Emacs 28?

If the behavior is the same there, yes.

bug#55562: 28.1.50; Wrong hash table return values in Elisp manual

[Basil L. Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

found 55562 24.1
close 55562 28.2
quit

Eli Zaretskii [2022-06-27 22:35 -0400] wrote:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  Daniel Colascione
>>  <dancol@dancol.org>,  55562@debbugs.gnu.org
>> Date: Mon, 27 Jun 2022 23:43:59 +0300
>> 
>> Is this suitable for Emacs 28?
>
> If the behavior is the same there, yes.

The puthash behaviour has been with us since Emacs 22, and the clrhash
behaviour since Emacs 24, it's just the Elisp manual that was never
updated accordingly.

So I've now updated the manual in emacs-28, and I'm closing this report.

Fix hash table function return values in manual
091b22cb12 2022-06-28 10:03:53 +0300
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=091b22cb12

Thanks,

-- 
Basil