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

Previous Next

Full log

Message #17 received at 35206 <at> debbugs.gnu.org (full text, mbox):

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

> From: Mattias Engdegård <mattiase <at> acm.org>
> Date: Tue, 9 Apr 2019 13:45:34 +0200
> Cc: 35206 <at> debbugs.gnu.org
> 
> > 
> > Comparison of KEY against the car of each ALIST element
> > is made using TESTFN, or `eq' if nil or omitted.
> 
> If no knowledge whatsoever of alists can be assumed on the part of the reader, perhaps this would be better:
> 
>    "Return the value associated with KEY in ALIST.
> +The value is the cdr of the first element in ALIST whose car is equal to KEY.
>  If KEY is not found in ALIST, return DEFAULT.
> -Use TESTFN to lookup in the alist if non-nil.  Otherwise, use `assq'.
> +Equality is defined by TESTFN or by `eq' if nil or omitted.

This is much better, IMO.  It is better than your previous proposal,
because the text is simpler and thus more clear.

However, a slight rewording would improve it even more:

  Find an element of ALIST whose `car' equals KEY and return its `cdr'.
  ...
  Equality with KEY is tested by TESTFN, defaulting to `eq'.

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.)

Thanks.

Previous Next

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