From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Emanuel Berg Newsgroups: gmane.emacs.devel Subject: Re: What's missing in ELisp that makes people want to use cl-lib? Date: Thu, 09 Nov 2023 14:59:46 +0100 Message-ID: <87sf5fhvsd.fsf@dataswamp.org> References: <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=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16915"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) To: emacs-devel@gnu.org Cancel-Lock: sha1:gcR7OS0hhRf0HWLMMRlNyHKZN28= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Nov 09 15:58:15 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 1r16U3-0004BE-8Y for ged-emacs-devel@m.gmane-mx.org; Thu, 09 Nov 2023 15:58:15 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r16TP-0006Mo-S5; Thu, 09 Nov 2023 09:57:36 -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 1r15Zj-0005LE-TM for emacs-devel@gnu.org; Thu, 09 Nov 2023 09:00:04 -0500 Original-Received: from ciao.gmane.io ([116.202.254.214]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r15Ze-0005T0-9A for emacs-devel@gnu.org; Thu, 09 Nov 2023 09:00:00 -0500 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1r15Za-0008YW-NG for emacs-devel@gnu.org; Thu, 09 Nov 2023 14:59:54 +0100 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: emacs-devel@gnu.org Mail-Copies-To: never Received-SPF: pass client-ip=116.202.254.214; envelope-from=ged-emacs-devel@m.gmane-mx.org; helo=ciao.gmane.io X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, HEADER_FROM_DIFFERENT_DOMAINS=0.25, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Thu, 09 Nov 2023 09:57:33 -0500 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:312415 Archived-At: João Távora wrote: > These are all internal functions and implementation details. > They're not necessary at all for users of cl-lib.el, only > for its developers. What problem are you trying to solve by > enhancing these docstrings? I thought the problem here was > code that _used_ cl-lib.el, not hacking on cl-lib.el itself. It is still nuch better than removing or rewriting it, so let's do that. We can use checkdoc to find out what docstrings are not submitted or not correctly formated. Those should be pretty quick fixes, to get away with those warnings. After we have done that, if someone says some specific docstring is still lacking we can focus on such individual cases in more detail. Here, to get the list from, e.g., cl-lib.el (defun check-package-style () (interactive) (let ((msg "Style check...")) (message msg) (checkdoc-current-buffer t) (message "%sdone" msg) )) And the list is cl-lib.el:133: Argument ‘keys’ should appear (as KEYS) in the doc string cl-lib.el:160: All variables and subroutines might as well have a documentation string cl-lib.el:166: All variables and subroutines might as well have a documentation string cl-lib.el:197: All variables and subroutines might as well have a documentation string cl-lib.el:197: All variables and subroutines might as well have a documentation string cl-lib.el:226: Arguments occur in the doc string out of order cl-lib.el:258: Argument ‘specs’ should appear (as SPECS) in the doc string cl-lib.el:357: Argument ‘cl-func’ should appear (as CL-FUNC) in the doc string cl-lib.el:450: Argument ‘rest’ should appear (as REST) in the doc string cl-lib.el:488: Argument ‘cl-item’ should appear (as CL-ITEM) in the doc string cl-lib.el:501: Argument ‘cl-new’ should appear (as CL-NEW) in the doc string cl-lib.el:510: All variables and subroutines might as well have a documentation string cl-lib.el:544: All variables and subroutines might as well have a documentation string cl-lib.el:582: Probably "returns" should be imperative "return" Here are all the cl-lib files cl-extra.el cl-generic.el cl-indent.el cl-lib.el cl-loaddefs.el cl-macs.el cl-preloaded.el cl-print.el cl-seq.el GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, cairo version 1.16.0) of 2023-11-01 [commit 8eb9b82ce58a8323af21f52625a401e19e279a9c] -- underground experts united https://dataswamp.org/~incal