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 15:11:35 +0000 Message-ID: References: <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="39199"; 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 16:12:33 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 1r1TBQ-000A00-Mb for ged-emacs-devel@m.gmane-mx.org; Fri, 10 Nov 2023 16:12:32 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r1TAe-00085G-Q5; Fri, 10 Nov 2023 10:11:44 -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 1r1TAb-000839-7Y for emacs-devel@gnu.org; Fri, 10 Nov 2023 10:11:41 -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 1r1TAZ-00076u-4t for emacs-devel@gnu.org; Fri, 10 Nov 2023 10:11:40 -0500 Original-Received: (qmail 40862 invoked by uid 3782); 10 Nov 2023 16:11:36 +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 16:11:35 +0100 Original-Received: (qmail 23345 invoked by uid 1000); 10 Nov 2023 15:11:35 -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:312499 Archived-At: Hello again, João. On Fri, Nov 10, 2023 at 14:35:38 +0000, João Távora wrote: > On Fri, Nov 10, 2023 at 2:25 PM Alan Mackenzie wrote: > > 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. > Those are not public functions, Alan. Even Dmitry pointed that out > immediately. The second set were public functions. And as Eli pointed out, non-public functions need documenting too. > > It seems to me you are going back on your undertaking to amend these > > five doc strings. > Stop insinuating that. You made an undertaking, the text of which was still in this thread until you snipped it from your last post. I now accept you won't be amending the doc strings I suggested, or probably any others. I think that's a shame, and I'm disappointed. > I'm sorry you lost time looking at those functions (by why???). But > it's not my fault you have no distinction of public/private interface. What sort of a smear is that meant to be? It's just that I'm aware of the need to document internal functions, you seem not to be. As a cl-lib enthusiast, you would have been best placed to fix this doc. > Or at least not one I share. But I do, and the Emacs documentation > does. The Emacs and Elisp manual doesn't describe '--' functions, > period. Even checkdoc.el has this concept. Docstrings for internal > functions don't hurt, but they're not the essential parts to describe > a library. Surely not the first things you should focus on, because > internals are by definition prone to one could re-implement all of > cl-lib.el keeping the same interfaces and their docstrings with wholly > new internals. I don't know why am I'm having to clarify this. I don't think there's much point continuing this bit of the conversation any further. > Anyway, take care, Alan. > João -- Alan Mackenzie (Nuremberg, Germany).