From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#35206: [PATCH] Misleading `list-get' argument description Date: Tue, 09 Apr 2019 17:41:28 +0300 Message-ID: <83a7gz6y1z.fsf@gnu.org> References: <77179D00-DAC7-41E9-BC76-4F0824DC57EF@acm.org> <83ef6b78aa.fsf@gnu.org> <29604A23-C01D-4DE5-9D40-493EAC445056@acm.org> <75D164EF-3F6F-4E45-ADCB-7A6C25DF4453@acm.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="241692"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 35206@debbugs.gnu.org To: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 09 16:42:13 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hDrwz-0010my-Dy for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 16:42:13 +0200 Original-Received: from localhost ([127.0.0.1]:42668 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDrwy-0005iP-FC for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 10:42:12 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:50096) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDrwt-0005i8-88 for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 10:42:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hDrwr-0007B0-AQ for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 10:42:07 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38292) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hDrwo-0007A2-Cp for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 10:42:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hDrwo-0003V2-8e for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 10:42:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 09 Apr 2019 14:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35206 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 35206-submit@debbugs.gnu.org id=B35206.155482089913418 (code B ref 35206); Tue, 09 Apr 2019 14:42:02 +0000 Original-Received: (at 35206) by debbugs.gnu.org; 9 Apr 2019 14:41:39 +0000 Original-Received: from localhost ([127.0.0.1]:51836 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDrwR-0003UM-GT for submit@debbugs.gnu.org; Tue, 09 Apr 2019 10:41:39 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:35625) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDrwQ-0003U6-Ac for 35206@debbugs.gnu.org; Tue, 09 Apr 2019 10:41:38 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:40825) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDrwK-0006fs-MB; Tue, 09 Apr 2019 10:41:32 -0400 Original-Received: from [176.228.60.248] (port=4715 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1hDrwI-00014E-Ke; Tue, 09 Apr 2019 10:41:31 -0400 In-reply-to: <75D164EF-3F6F-4E45-ADCB-7A6C25DF4453@acm.org> (message from Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= on Tue, 9 Apr 2019 13:45:34 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:157419 Archived-At: > From: Mattias Engdegård > Date: Tue, 9 Apr 2019 13:45:34 +0200 > Cc: 35206@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.