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: Thu, 9 Nov 2023 13:07:42 +0000 Message-ID: References: <871qd8sfdx.fsf@posteo.net> <838r7g8pys.fsf@gnu.org> <87bkcbrgnr.fsf@posteo.net> <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=iso-8859-1 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7316"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Gerd =?iso-8859-1?Q?M=F6llmann?= , =?iso-8859-1?Q?Bj=F6rn?= Bidar , emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Nov 09 14:08:46 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 1r14m6-0001iz-4x for ged-emacs-devel@m.gmane-mx.org; Thu, 09 Nov 2023 14:08:46 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r14lH-0004Hk-9c; Thu, 09 Nov 2023 08:07:55 -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 1r14lF-0004Gk-AF for emacs-devel@gnu.org; Thu, 09 Nov 2023 08:07:53 -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 1r14l9-0000o4-Sq for emacs-devel@gnu.org; Thu, 09 Nov 2023 08:07:53 -0500 Original-Received: (qmail 36408 invoked by uid 3782); 9 Nov 2023 14:07:43 +0100 Original-Received: from acm.muc.de (p4fe15b72.dip0.t-ipconnect.de [79.225.91.114]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 09 Nov 2023 14:07:42 +0100 Original-Received: (qmail 4659 invoked by uid 1000); 9 Nov 2023 13:07:42 -0000 Content-Disposition: inline In-Reply-To: <8a7362da-3cc4-221c-7b8a-a9918677adff@gutov.dev> 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:312405 Archived-At: Hello, Dmitry. On Thu, Nov 09, 2023 at 13:48:34 +0200, Dmitry Gutov wrote: > On 09/11/2023 12:34, Alan Mackenzie wrote: > > As a concrete plan, I would propose the following for discussion: > > We should deprecate those functions/macros/variables in cl-lib that have > > no doc string, or a substandard one. This includes "internal" functions, > > too. Also to be deprecated are obscure functions/m/v (such as > > cl-labels). > I'm not sure we can remove cl-labels -- it's useful enough for the cases > where it does help, and there are callers inside and outside of Emacs. > Whatever other removals, would probably need to be discussed case-by-case. There are probably too many such functions/macros/variables to make that practicable. If we did do this, the discussion for each f/m/v would likely balloon out into a thread as long as this one, and nothing much would get done. > > Having done this, we recode code currently using those deprecated f/m/v. > > (Here a "substandard" doc string is contrasted with an adequate one, > > which does all of the following: > > (i) It says what the function/macro_does_, or what the variable_is_. > > (ii) It describes the form and meaning of each parameter, and its > > relationship to (i). > > (iii) If the return value is significant, it describes this. > > (iv) It describes all effects on the global state, such as where it > > writes results to, and suchlike.) > Improving cl-lib's documentation would be a welcome effort. Yes, people have been saying this for years. I wrote a chapter on cl-print.el for cl.info a couple of months back. Other than that nobody seems prepared to do anything much on this front. What is needed is a sustained effort from a cl-lib enthusiast to fix the 50 - 100 doc strings which are missing or substandard. Well, Joćo has offered to start off with 5 doc strings, which is good. Maybe something will come of that. -- Alan Mackenzie (Nuremberg, Germany).