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 14:00:29 +0300 Message-ID: <83ef6b78aa.fsf@gnu.org> References: <77179D00-DAC7-41E9-BC76-4F0824DC57EF@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="78662"; 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 13:01:16 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 1hDoVA-000KLr-KF for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 13:01:16 +0200 Original-Received: from localhost ([127.0.0.1]:39142 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDoV9-00041c-Kj for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 07:01:15 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:54781) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDoV4-00041W-4L for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 07:01:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hDoV0-0000ex-CD for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 07:01:08 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:37066) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hDoUw-0000cf-BO for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 07:01:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hDoUw-0001pU-6O for bug-gnu-emacs@gnu.org; Tue, 09 Apr 2019 07:01: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 11:01: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.15548076426995 (code B ref 35206); Tue, 09 Apr 2019 11:01:02 +0000 Original-Received: (at 35206) by debbugs.gnu.org; 9 Apr 2019 11:00:42 +0000 Original-Received: from localhost ([127.0.0.1]:50610 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDoUb-0001ol-US for submit@debbugs.gnu.org; Tue, 09 Apr 2019 07:00:42 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:40289) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDoUa-0001oZ-1J for 35206@debbugs.gnu.org; Tue, 09 Apr 2019 07:00:40 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:37200) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDoUU-0000G0-BU; Tue, 09 Apr 2019 07:00:34 -0400 Original-Received: from [176.228.60.248] (port=2923 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1hDoUS-0007W3-Ch; Tue, 09 Apr 2019 07:00:33 -0400 In-reply-to: <77179D00-DAC7-41E9-BC76-4F0824DC57EF@acm.org> (message from Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= on Tue, 9 Apr 2019 12:34:09 +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:157404 Archived-At: > From: Mattias Engdegård > 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.