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

[Basil L. Contovounesios]

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