From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'. Date: Tue, 19 Jan 2016 20:32:53 +0200 Message-ID: <83h9i9besq.fsf@gnu.org> References: <20160116143238.27391.97533@vcs.savannah.gnu.org> <8737ttx5dm.fsf@web.de> <83oachbgz0.fsf@gnu.org> <87vb6pih39.fsf@web.de> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453228394 22865 80.91.229.3 (19 Jan 2016 18:33:14 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 19 Jan 2016 18:33:14 +0000 (UTC) Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Michael Heerdegen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jan 19 19:33:05 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aLb5U-0004BW-R9 for ged-emacs-devel@m.gmane.org; Tue, 19 Jan 2016 19:33:04 +0100 Original-Received: from localhost ([::1]:38769 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aLb5T-0002yY-V8 for ged-emacs-devel@m.gmane.org; Tue, 19 Jan 2016 13:33:03 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58702) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aLb5H-0002xi-B7 for emacs-devel@gnu.org; Tue, 19 Jan 2016 13:32:52 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aLb5G-00074O-HR for emacs-devel@gnu.org; Tue, 19 Jan 2016 13:32:51 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:35487) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aLb5C-00073A-FN; Tue, 19 Jan 2016 13:32:46 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2264 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aLb5A-0007O7-G2; Tue, 19 Jan 2016 13:32:45 -0500 In-reply-to: <87vb6pih39.fsf@web.de> (message from Michael Heerdegen on Tue, 19 Jan 2016 19:01:30 +0100) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:198376 Archived-At: > From: Michael Heerdegen > Cc: emacs-devel@gnu.org, Stefan Monnier > Date: Tue, 19 Jan 2016 19:01:30 +0100 > > > I don't know -- should we? I didn't find any other function for which > > we say something like that, so saw no reason to single this one out. > > I think setf'ing alist-get is the preferred way now to change the value > associated to a key. If it is, it should be discoverable in some way, > because it is an important functionality. Unlike other functions that > are setf'able, in this case we have no equivalent setter function > defined, i think. Isn't 'cdr' also in that class? As well as at least a few others? AFAIU, this function just saves you from the need to repeatedly test the value returned by assq before using it, that's all. I don't see what's so exciting about that. We have similar tricks, some of them gems, all over the place, and there's no practical way we could make them stand out enough, not when we have almost 2000 functions, macros, and special forms documented in the manual (and many more not documented). The only way is for people to read well-written code and learn. No manual can ever replace that. > I think the docstring should be improved. AFAICT the REMOVE arg makes > only sense when using the function with a gv setter. For the record, that doc string almost made me weep in frustration -- about my own stupidity, no doubt, since I couldn't make heads or tails out of it, when I compared it with the actual code (including studying the _only_ use of it in the context of a gv setter, AFAICT).