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

[Eli Zaretskii <eliz@gnu.org>]

> From: Mattias Engdegård <mattiase@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.