GNU bug report logs - #35206
[PATCH] Misleading `list-get' argument description

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: 35206 <at> debbugs.gnu.org
Subject: bug#35206: [PATCH] Misleading `list-get' argument description
Date: Tue, 09 Apr 2019 14:00:29 +0300

> From: Mattias Engdegård <mattiase <at> acm.org>
> Date: Tue, 9 Apr 2019 12:34:09 +0200
> 
> 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.

IMO, this has a problem similar to the original text: it has nothing
to "connect" it to the main part of the doc string, which is this:

  Return the value associated with KEY in ALIST.

Neither "look up" nor "equality" is directly and obviously related to
"associated with".  E.g., you probably like "equality" better because
your mental model of "associated with" is a test for equality;
however, someone else might prefer the current text because they think
of "looking up" in the same situation.  But the text doesn't make the
relation explicit, and that is IMO its main problem.

Can you think of a change that would resolve this problem?

Thanks.

Previous Next

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