From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: What's missing in ELisp that makes people want to use cl-lib? Date: Fri, 10 Nov 2023 14:25:30 +0000 Message-ID: References: <87bkc4jpja.fsf@dataswamp.org> <8a7362da-3cc4-221c-7b8a-a9918677adff@gutov.dev> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6282"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Dmitry Gutov , Gerd =?iso-8859-1?Q?M=F6llmann?= , =?iso-8859-1?Q?Bj=F6rn?= Bidar , emacs-devel@gnu.org To: =?iso-8859-1?Q?Jo=E3o_T=E1vora?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Nov 10 15:26:14 2023 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1r1SSc-0001OX-0W for ged-emacs-devel@m.gmane-mx.org; Fri, 10 Nov 2023 15:26:14 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r1SS4-0001oJ-Sp; Fri, 10 Nov 2023 09:25:41 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r1SS2-0001kM-6Z for emacs-devel@gnu.org; Fri, 10 Nov 2023 09:25:39 -0500 Original-Received: from mail.muc.de ([193.149.48.3]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r1SRz-0004LC-Ej for emacs-devel@gnu.org; Fri, 10 Nov 2023 09:25:37 -0500 Original-Received: (qmail 88517 invoked by uid 3782); 10 Nov 2023 15:25:31 +0100 Original-Received: from acm.muc.de (p4fe158a9.dip0.t-ipconnect.de [79.225.88.169]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 10 Nov 2023 15:25:31 +0100 Original-Received: (qmail 21574 invoked by uid 1000); 10 Nov 2023 14:25:30 -0000 Content-Disposition: inline In-Reply-To: X-Submission-Agent: TMDA/1.3.x (Ph3nix) X-Primary-Address: acm@muc.de Received-SPF: pass client-ip=193.149.48.3; envelope-from=acm@muc.de; helo=mail.muc.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:312494 Archived-At: Hello, João. On Fri, Nov 10, 2023 at 12:53:10 +0000, João Távora wrote: > On Fri, Nov 10, 2023 at 12:13 PM Alan Mackenzie wrote: > > On Thu, Nov 09, 2023 at 13:41:48 +0000, João Távora wrote: > > > On Thu, Nov 9, 2023 at 1:36 PM Alan Mackenzie wrote: > > > > On Thu, Nov 09, 2023 at 12:40:24 +0000, João Távora wrote: > > > > > On Thu, Nov 9, 2023 at 11:49 AM Dmitry Gutov wrote: > > > > > > Improving cl-lib's documentation would be a welcome effort. > > > > > For sure, and not a hard one as well, as all those functions and > > > > > macros are pretty good, often flawless emulations of CL functions that > > > > > are impeccably documented in > > > > > http://www.lispworks.com/documentation/HyperSpec/Front/ > > > > > Which is of free access (though not of a compatible license, I > > > > > think). But if people can point to the 5 most confusing functions > > > > > they think are poorly documented, I volunteer to rewrite the > > > > > docstrings for them. > > > > How much are you prepared to do? I don't have a list of the _most_ > > > > confusing doc strings, there are too many to chose from. But starting > > > > at the start of cl-macs.el, we have: > > > > (i) cl--compiler-macro-list*; completely undocumented. > > > > (ii) cl--simple-expr-p: Talks about "side effects", but not what they > > > > are side effects of. Doesn't describe it's parameters or return > > > > value. It's unclear what it is that "executes quickly". > > > > (iii) cl--expr-contains: It's unclear what X and Y are, and what "refers > > > > to" means. > > > > (iv) cl--expr-contains-any; completely undocumented. > > > > (v) cl--expr-depends-p: It's unclear what X and Y are, though Y appears > > > > to be some sort of container of symbols. It's unclear what sort of > > > > "dependency" the function handles, or what "may" means in the context. > > > > There are many more. > > > These are all internal functions and implementation details. They're > > > not necessary at all for users of cl-lib.el, only for its developers. > > So, you're not prepared to rewrite their doc strings as you promised > > yesterday, any more. > I thought the whole problem is that code using cl-lib.el is hard to use. More precisely, it's hard to understand and to debug, precisely because it uses cl-* functions. > You said cl-labels was "obscure", so I was prepared to enhance its > docstring, yes. That's a public macro. Along with 4 other "obscure" > public ones. Ah, so your offer of fixing 5 doc strings is limited to obscure objects. That wasn't clear from the outset, and wasn't what you said. Documentation won't help cl-labels become any less obscure. I've debugged code using it, but I havn't any clue what it does. There is nothing about its functionality which sticks in memory. Its name is poor - "labels" isn't a verb, and what it does has nothing to do with labels. > Documentation cl-lib's implementation details is something else > entirely. It doesn't hurt if there's suspicion that cl-lib.el is > misbehaving in function or efficiency. But that's not the matter in > discussion here and it doesn't solve the presumed problem of not > understanding code that makes uses cl-lib. It would solve part of the problem. > > > What problem are you trying to solve by enhancing these docstrings? > > Being able to debug Emacs problems. > What problem specifically are you having trouble with? What do you > ultimately want to achieve that you can't without docstrings for > cl-lib.el's implementation details. This might be an XY problem > (https://en.wikipedia.org/wiki/XY_problem) I'm not having any specific problem at the moment. The need for accurate readable doc strings, particularly for code as difficult and obscure as cl-*, should be self-evident. I don't know what an "XY problem" is and can't be bothered to look up your reference. Thanks for not explaining clearly what you mean. > > cl-lib uses itself, and needs debugging too. Debugging code that uses > > abstractions often requires penetrating these abstractions and checking > > their innards. > Well, no. I don't go read OS source code whenever I have doubts > about how to use a system call or how to read a given piece of > code that uses that system call, I read the manual page for the system > call itself. One Emacs bug I solved involved hacking into the Linux kernel. The solution to the bug was to upgrade to a specific kernel version or later. > Just as I don't pull up a magnifying glass to check if my CPU's > transistors are doing what they should, I trust the data sheet > describing the instructions. So, no, at least not desirably. That's > the whole argument for good docstrings: that it relieves you from > having to penetrate innards to understand a function's interface. > Feels a bit odd to be defending age-old ideas of encapsulation and > information-hiding here. Total strawman argument. > To summarize, I thought it would be absolutely clear that I volunteered > to write docstrings for public functions, public interfaces. No, it wasn't clear. > I'm amazed it wasn't, but I apologize for the misunderstanding > nonetheless. Docstrings for things that the user sees, is confused by, > finds obscure, etc. Give me 5 of those, and I'll rework their > docstrings for clarity. I did so in my last post, and you've just snipped them without comment. That's twice I've given you five bad doc strings, and you aren't acting on either set. That took a significant amount of my time. Thanks. It seems to me you are going back on your undertaking to amend these five doc strings. > I suggest cl-labels since you singled it out and some sequence > manipulating functions which just say: "Keywords supported: :test > :test-not :key :start :end :from-end" but don't explain what each of > those keyword arguments do. That would certainly be useful, yes. > Another useful thing would be to extend eldoc support in Elisp mode > to be able to highlight the currently active keyword argument. I'll > also look into that, but no promises. That is something else entirely, unrelated to the poor quality of the doc strings that we're talking about. > Thanks, > João -- Alan Mackenzie (Nuremberg, Germany).