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 12:13:25 +0000 Message-ID: References: <25924.21015.19614.951576@orion.rgrjr.com> <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="14482"; 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 13:14:00 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 1r1QOe-0003Vf-7P for ged-emacs-devel@m.gmane-mx.org; Fri, 10 Nov 2023 13:14:00 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r1QOD-0003cM-WD; Fri, 10 Nov 2023 07:13:34 -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 1r1QOC-0003bZ-AS for emacs-devel@gnu.org; Fri, 10 Nov 2023 07:13:32 -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 1r1QO9-0000gd-2P for emacs-devel@gnu.org; Fri, 10 Nov 2023 07:13:31 -0500 Original-Received: (qmail 37988 invoked by uid 3782); 10 Nov 2023 13:13:25 +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 13:13:25 +0100 Original-Received: (qmail 21430 invoked by uid 1000); 10 Nov 2023 12:13:25 -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:312479 Archived-At: Hello, João. 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: > > Hello, João. > > 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. > What problem are you trying to solve by enhancing these docstrings? Being able to debug Emacs problems. > I thought the problem here was code that _used_ cl-lib.el, not hacking > on cl-lib.el itself. cl-lib uses itself, and needs debugging too. Debugging code that uses abstractions often requires penetrating these abstractions and checking their innards. Still, if you're not prepared to fix doc strings in internal functions, here are five external functions with inadequate doc strings: (i) cl-fill: The doc string misnames some of the parameters. It is unclear what "fill" means, and the forms of CL-SEQ and CL-ITEM aren't specified. Is each element of CL-SEQ "filled" with the entirety of CL-ITEM, or what? Finally, there is no documentation of CL-KEYS, beyond stating that two particular keywords are "supported", whatever that means. What do :start and :end actually do? The return value is not specified. (ii) cl-replace: Much the same problems as for cl-fill. (iii) cl-remove: Same again. Additionally, it is not specified what an "occurrence" is; this presumably involves some equality test, and which one is used is not specified. Again the effect of the keywords is unspecified. There are keywords used in its code which aren't listed in the doc string, namely :if and :if-not. (iv) cl-remove-if: Much the same again. (v) cl-remove-if-not: ... and again. I found these simply by starting at the beginning of cl-seq and listing pretty much each external function I found in a simple search. There are a lot more like these. Still, even having just those five things properly documented would be worthwhile. Thanks for volunteering to do this! > João -- Alan Mackenzie (Nuremberg, Germany).