Subject: bug#35206: closed (Re: bug#35206: [PATCH] Misleading `list-get' argument description)

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 09 Apr 2019 15:00:03 +0000

Your bug report

#35206: [PATCH] Misleading `list-get' argument description

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
35206: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=35206
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#35206: [PATCH] Misleading `list-get' argument description
From: Mattias Engdegård <[email-masked]>
To: Eli Zaretskii <[email-masked]>
Cc: [email-masked]
Date: Tue, 9 Apr 2019 16:59:48 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

9 apr. 2019 kl. 16.41 skrev Eli Zaretskii <[email-masked]>:
> 
>  Find an element of ALIST whose `car' equals KEY and return its `cdr'.
>  ...
>  Equality with KEY is tested by TESTFN, defaulting to `eq'.

Thank you, I pushed that change (except that I used "the first element" instead of "an element" for precision).

> IMO, this isn't about assuming knowledge, this is about being as
> explicit as reasonably possible about what the function does.
> (Strictly speaking, both your suggestion and mine still assume some
> knowledge about alists, because we never explain what is an alist, nor
> what is an "element" of an alist.)

That's all right -- I was mainly concerned with the quite misleading TESTFN description, and looked at the docs of similar functions (assq, assoc).

Subject: [PATCH] Misleading `list-get' argument description
From: Mattias Engdegård <[email-masked]>
To: [email-masked]
Date: Tue, 9 Apr 2019 12:34:09 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

The doc string for `list-get' says

  Use TESTFN to lookup in the alist if non-nil.  Otherwise, use `assq'.

which is misleading since it's an equality predicate, not a look-up function, and the default is `eq', not `assq'.
How about changing it to

  Equality is defined by TESTFN or by `eq' if nil or omitted.