From unknown Fri Jun 20 07:12:50 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#78543 <78543@debbugs.gnu.org> To: bug#78543 <78543@debbugs.gnu.org> Subject: Status: 29.2; checkdoc misses some CL (cl-lib) constructs. Reply-To: bug#78543 <78543@debbugs.gnu.org> Date: Fri, 20 Jun 2025 14:12:50 +0000 retitle 78543 29.2; checkdoc misses some CL (cl-lib) constructs. reassign 78543 emacs submitter 78543 Marco Antoniotti severity 78543 normal thanks From debbugs-submit-bounces@debbugs.gnu.org Wed May 21 16:39:16 2025 Received: (at submit) by debbugs.gnu.org; 21 May 2025 20:39:17 +0000 Received: from localhost ([127.0.0.1]:53484 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uHqDc-0007V4-HW for submit@debbugs.gnu.org; Wed, 21 May 2025 16:39:16 -0400 Received: from lists.gnu.org ([2001:470:142::17]:39230) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uHqDY-0007UE-Rm for submit@debbugs.gnu.org; Wed, 21 May 2025 16:39:13 -0400 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 1uHqDT-0007zl-AJ for bug-gnu-emacs@gnu.org; Wed, 21 May 2025 16:39:07 -0400 Received: from mail-yb1-xb30.google.com ([2607:f8b0:4864:20::b30]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1uHqDR-0007GK-FV for bug-gnu-emacs@gnu.org; Wed, 21 May 2025 16:39:07 -0400 Received: by mail-yb1-xb30.google.com with SMTP id 3f1490d57ef6-e7912134bfaso829347276.0 for ; Wed, 21 May 2025 13:39:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1747859941; x=1748464741; darn=gnu.org; h=to:subject:message-id:date:from:mime-version:from:to:cc:subject :date:message-id:reply-to; bh=+pmzuJ0D61xrLdOwgz/P7bVlcdD6FVVQjp+2K48BiDk=; b=EIsMroQ5trTEKKnF+O2SJMjGA106jz4HOgQAh1ZWa4kfk3U51fkR/PtQlovEUp6RfH K1s+A0b9Inh+uuTfJXTmq692UpQFYZB9fsiUE111Tc1S47A2Qc+5a4K6VJODKXqOAURT +rD7NaE1U37SxkNLxD31l0oFw9kufvh22ICq/R316zvRGZPAm5DH1SvqzNe/nmCnkyX4 hNkA1qCZCzkGS44VWnPu9AkMHtG30PFLm5fBEwqgBpr/+f9vnv9WP7ZVfc9Rd7pNIMdQ KgLHhIHOOj3MjLNKSQP3ITxQ2vx+u4z83O+9AX5G8TLqfmlze4CpDVcDsziYdy0lvvOr 0lnA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1747859941; x=1748464741; h=to:subject:message-id:date:from:mime-version:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=+pmzuJ0D61xrLdOwgz/P7bVlcdD6FVVQjp+2K48BiDk=; b=UZhJ8o+gvnZmJq4GT9LbFvcCacHiTRGGngUgTxvTIibGumJEpwnFwvXHno5zGaq2oA DkR69fMbyCYS9C/kVK9d9y/xPR1vZvxEoFv1I3QlFd+pTPLoyLQaZqeiOCT9u065t42m 8JoVb4MKUbqkct0AlqQJp6h07NvrboOrAYE4MFhljeOuWl411CaPXfS3HF6wsdx9RnYl M9cI7xlYibs3/esgPBuA4OSAKu2JLCT8SoUwUca9fN9yamYJ8nOEDFYBauq8riBU0719 cnOMGLk/iuP2+PZ3CDOMpvyr/ugJ5Du//6zd3vzdVOlC77czTWtxqPdX4OsUGdCcjyFW TArA== X-Gm-Message-State: AOJu0YzmpsjsjGMSNdth+rrMTaL3ISlhr3NKvI+qXYgs3+XAemhFnHtB klru7eJhgtoFCl+Ec+Ow39MDqdYkkpf4+E2zmedOwb838PNXcg80TkFyU5rWkasyFMr9MNXK8Bj E03xxJ+f4X0rWuhx8TZLfYq2aa69IhFGC6bFUq0M= X-Gm-Gg: ASbGncswPRBCScqtSDh/Tx15vaxUJ74XVermX5b5P8XzUEsRUHmb4I5xa525hcrAsHi Fmh5yiraZ+rSmZYYlnn71IOJODW1fF6X4sJsumuQDXxuKfIzesrB9TAnXoLBZwJOGIuyx0Lu/Fl nqIS2i6lU8zhJALv6I5Pm85b4OtejsAJjzlw== X-Google-Smtp-Source: AGHT+IGvtGX3rLyxFf+8KRRM6i8PvEN1U8RQ+kpYJ4Hxq9J/0D6qDrS7/1MqICzsHuuf+VPSgdwBLKr1YOmWx5OIHQg= X-Received: by 2002:a05:6902:320f:b0:e7b:3639:262a with SMTP id 3f1490d57ef6-e7b697985ffmr12348818276.0.1747859940956; Wed, 21 May 2025 13:39:00 -0700 (PDT) MIME-Version: 1.0 From: Marco Antoniotti Date: Wed, 21 May 2025 22:38:48 +0200 X-Gm-Features: AX0GCFtijQHknkrG2D5n9jYoJUImpA8gth8CX0HWYT3Sxw4rPI1bwBrjLKXQ8qA Message-ID: Subject: 29.2; checkdoc misses some CL (cl-lib) constructs. To: bug-gnu-emacs@gnu.org Content-Type: multipart/alternative; boundary="000000000000e5e3910635ab5afc" Received-SPF: pass client-ip=2607:f8b0:4864:20::b30; envelope-from=marcoxa@gmail.com; helo=mail-yb1-xb30.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) --000000000000e5e3910635ab5afc Content-Type: text/plain; charset="UTF-8" Hi The problem is with `checkdoc` not correctly handling some docstring in `cl-lib` style declarations. I have a function like ``` (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) "Do something with THAT (passed via :THIS)" ... ) ``` checkdoc insists on flagging :THIS and THE-BEAST as missing from the docstring. Another one is the following. ``` (cl-defgeneric gf (a s d f) (:documentation "Munge A, S, D, and F.")) ``` checkdoc does not recognize the :documentation option (which is valid according to cl-lib). This problem is still visible in 30.1 All the best Marco -- Marco Antoniotti Somewhere over the Rainbow --000000000000e5e3910635ab5afc Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi

The problem is with `checkdoc` not correctl= y handling some docstring
in `cl-lib` style declarations.

I have = a function like

```
(cl-defun funky-keys (&key ((:this that) = 42) &aux (the-beast 666))
=C2=A0 =C2=A0 "Do something with THAT= (passed via :THIS)"
=C2=A0 =C2=A0 ...
=C2=A0 =C2=A0 )
```
checkdoc insists on flagging :THIS and THE-BEAST as missing from the d= ocstring.

Another one is the following.

```
(cl-defgeneric= gf (a s d f)
=C2=A0 =C2=A0 (:documentation "Munge A, S, D, and F.&= quot;))
```

checkdoc does not recognize the :documentation option= (which is valid according to cl-lib).

This proble= m is still visible in 30.1

All the best

Mar= co


--=
Marco Antoniotti
Somewhere over the Rainbow
--000000000000e5e3910635ab5afc-- From debbugs-submit-bounces@debbugs.gnu.org Sat May 31 07:07:58 2025 Received: (at 78543) by debbugs.gnu.org; 31 May 2025 11:07:58 +0000 Received: from localhost ([127.0.0.1]:56225 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLK4D-0007Ka-Pe for submit@debbugs.gnu.org; Sat, 31 May 2025 07:07:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57526) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uLK4A-0007K4-M8 for 78543@debbugs.gnu.org; Sat, 31 May 2025 07:07:55 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uLK45-0005Ms-7z; Sat, 31 May 2025 07:07:49 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=avKotQ05dIZugX9i7KPh5pSl4cOMOuFKJDZk9ZvRgoY=; b=lzsfrSRrZSUR mqchICakUfvl4nYk3oQL7306zqjC7ugPzzTBCzmLgmFT17wS8Q4n65CPujal2Bx/5WXLEHB4Y4DEm JvMD2Ysk148ENSzjdbTaiXeKTDEuajNGlDR5jnqaB0XnldBJ4aZHKIJ2Y5yI/IAPSqNCJah7R4HQu nC04ckLLSX1LzE24g5RkikEH5coFAw0OZqSU+LL9VbI7xiUSx2PkJVDreaOGyFQeVmNGTiXUi2dhJ QffaIEFzqncLnIW3yBKngHCgLpSJVokgrU6U1mfoj4VmQH7yyr7ekAUWwfIn7VoBooulkL5wOPCmN DTmOIussgb03IizmD9zBDg==; Date: Sat, 31 May 2025 14:07:46 +0300 Message-Id: <86h611rqbh.fsf@gnu.org> From: Eli Zaretskii To: Marco Antoniotti , Stefan Monnier In-Reply-To: (message from Marco Antoniotti on Wed, 21 May 2025 22:38:48 +0200) Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. References: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 78543 Cc: 78543@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Marco Antoniotti > Date: Wed, 21 May 2025 22:38:48 +0200 > > The problem is with `checkdoc` not correctly handling some docstring > in `cl-lib` style declarations. > > I have a function like > > ``` > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > "Do something with THAT (passed via :THIS)" > ... > ) > ``` > > checkdoc insists on flagging :THIS and THE-BEAST as missing from the docstring. > > Another one is the following. > > ``` > (cl-defgeneric gf (a s d f) > (:documentation "Munge A, S, D, and F.")) > ``` > > checkdoc does not recognize the :documentation option (which is valid according to cl-lib). > > This problem is still visible in 30.1 Sigh. This is notoriously under-documented in the cl.info manual. After reading and re-reading the node "Argument Lists" there, I believe that we expect :this to be referenced as "THIS" (without the leading colon) in the doc string, since argument references in doc strings should be words, not symbols, and ':' is not a word-constituent character. Also, I believe that THE-BEAST should indeed be mentioned in the doc string. This: (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) "Do something with THAT (passed via THIS), binding THE-BEAST to 666." nil ) passes the checkdoc tests, if we install the simple patch below. But since I'm very far from being an expert of cl-defun and its correct usage, I invite CL experts to chime in and provide their opinions. Here's the patch which I will install barring any objections: diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el index 355a0c5..f9fab0b 100644 --- a/lisp/emacs-lisp/checkdoc.el +++ b/lisp/emacs-lisp/checkdoc.el @@ -1761,24 +1761,31 @@ checkdoc-this-string-valid-engine ;; Addendum: Make sure they appear in the doc in the same ;; order that they are found in the arg list. - (let ((args (nthcdr 4 fp)) - (last-pos 0) - (found 1) - (order (and (nth 3 fp) (car (nth 3 fp)))) - (nocheck (append '("&optional" "&rest" "&key" "&aux" - "&context" "&environment" "&whole" - "&body" "&allow-other-keys" "nil") - (nth 3 fp))) + (let* ((args (nthcdr 4 fp)) + (this-arg (car args)) + (this-arg (if (string-prefix-p ":" this-arg) + (substring this-arg 1) + this-arg)) + (last-pos 0) + (found 1) + (order (and (nth 3 fp) (car (nth 3 fp)))) + (nocheck (append '("&optional" "&rest" "&key" "&aux" + "&context" "&environment" "&whole" + "&body" "&allow-other-keys" "nil") + (nth 3 fp))) (inopts nil)) (while (and args found (> found last-pos)) (if (or (member (car args) nocheck) - (string-match "\\`_" (car args))) + (string-match "\\`_" this-arg)) (setq args (cdr args) + this-arg (if (string-prefix-p ":" (car args)) + (substring (car args) 1) + (car args)) inopts t) (setq last-pos found found (save-excursion (re-search-forward - (concat "\\<" (upcase (car args)) + (concat "\\<" (upcase this-arg) ;; Require whitespace OR ;; ITEMth OR ;; ITEMs @@ -1791,7 +1798,7 @@ checkdoc-this-string-valid-engine ;; and see if the user wants to capitalize it. (if (save-excursion (re-search-forward - (concat "\\<\\(" (car args) + (concat "\\<\\(" this-arg ;; Require whitespace OR ;; ITEMth OR ;; ITEMs @@ -1801,10 +1808,15 @@ checkdoc-this-string-valid-engine (match-beginning 1) (match-end 1) (format-message "If this is the argument `%s', it should appear as %s. Fix?" - (car args) (upcase (car args))) - (upcase (car args)) t) + this-arg (upcase this-arg)) + (upcase this-args) t) (setq found (match-beginning 1)))))) - (if found (setq args (cdr args))))) + (if found (setq args + (cdr args) + this-arg (if (string-prefix-p ":" + (car args)) + (substring (car args) 1) + (car args)))))) (if (not found) ;; It wasn't found at all! Offer to attach this new symbol ;; to the end of the documentation string. @@ -1817,7 +1829,7 @@ checkdoc-this-string-valid-engine (goto-char e) (forward-char -1) (insert "\n" (if inopts "Optional a" "A") - "rgument " (upcase (car args)) + "rgument " (upcase this-arg) " ") (insert (read-string "Describe: ")) (if (not (save-excursion (forward-char -1) @@ -1828,7 +1840,7 @@ checkdoc-this-string-valid-engine (checkdoc-create-error (format-message "Argument `%s' should appear (as %s) in the doc string" - (car args) (upcase (car args))) + (car args) (upcase this-arg)) s (marker-position e)))) (if (or (and order (eq order 'yes)) (and (not order) checkdoc-arguments-in-order-flag)) From debbugs-submit-bounces@debbugs.gnu.org Sat May 31 11:05:17 2025 Received: (at 78543) by debbugs.gnu.org; 31 May 2025 15:05:17 +0000 Received: from localhost ([127.0.0.1]:58854 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLNls-0002FM-Jm for submit@debbugs.gnu.org; Sat, 31 May 2025 11:05:17 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:36734) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uLNlq-0002Cf-5C for 78543@debbugs.gnu.org; Sat, 31 May 2025 11:05:14 -0400 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id E5508440A47; Sat, 31 May 2025 10:56:22 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1748703382; bh=01SkszEVWbDzcTMPSKpucWfoK3Yka86ETq7aXPmUtzI=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=bQf5H/vtE3AxOvc4+5DB9/GJIxze3tku5Fbk5G1N51iwoIyl1XErvKgqM28wAkJaW TaaV/AOjHNytTveOoGTQn4yLZZQoO+987+mOgvq5lRM5vjEHAr2HN6M1hUkeXSmRur VsH+QWIHUYYjgrjC2/fXic+oqoON6ihaN1hUhkHhZ9vO2fJC/58xz0met+Ej+ndHht yykWU67G1u8+YTMoTVbRzhf3TJB5mnVs7RbxCxIc7ce4mANha8+Cj2sVXYfJUPO55m qCkx/Fe462AHabsCh51Y0QW3QKZ80V0xTPz0FiJOqPMe+F1qWMs+rcVtu6iNWO+RGd qqdJzxkI3hkuw== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id EA8454409A4; Sat, 31 May 2025 10:56:21 -0400 (EDT) Received: from alfajor (unknown [104.247.225.139]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id BB18C12058B; Sat, 31 May 2025 10:56:21 -0400 (EDT) From: Stefan Monnier To: Eli Zaretskii Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. In-Reply-To: <86h611rqbh.fsf@gnu.org> Message-ID: References: <86h611rqbh.fsf@gnu.org> Date: Sat, 31 May 2025 10:56:19 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL -0.350 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 78543 Cc: Marco Antoniotti , 78543@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) >> ``` >> (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) >> "Do something with THAT (passed via :THIS)" >> ... >> ) >> ``` FWIW, I consider this `(:this that)` of CL's keyword args to be a misfeature, so I'm happy for Emacs to behave suboptimally here, tho I'd prefer for cl-lib to stop supporting it. > Also, I believe that THE-BEAST should > indeed be mentioned in the doc string. Why? It's not part of the function's exposed interface. It's just a weird way to define a local variable. I also find this `&aux` thingy to be a misfeature in CL, which we usually shouldn't support [ tho currently it's admittedly handy at times in `cl-defstruct` constructors. ], so I'm not sure it's worth complicating checkdoc for it. Stefan From debbugs-submit-bounces@debbugs.gnu.org Sat May 31 12:21:11 2025 Received: (at 78543) by debbugs.gnu.org; 31 May 2025 16:21:11 +0000 Received: from localhost ([127.0.0.1]:59229 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLOxK-00056I-PR for submit@debbugs.gnu.org; Sat, 31 May 2025 12:21:11 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54808) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uLOxG-00054R-Q1 for 78543@debbugs.gnu.org; Sat, 31 May 2025 12:21:08 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uLOxA-0004cI-QF; Sat, 31 May 2025 12:21:00 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=fjhvKceseHQ7u4hDQrmeRtUuh8JhQLkFU4hiTVhx8HU=; b=DZvkbUp0L1pk TZHU3DFKehCpzPJi36d5zItQVAjIlsOIUmov6vwpFyUp09KmsNZDqP62OL5m0Y+wS1CNaS6dAecPN qvwASJIz7Id0at0lzZPSZQVD0n9yLmSjJdOt0eBEtN27pre9vWN0kAxKfFmiLoQClfP+VsfWYCj6Q UMqAjbII8Xm4EboeuLHJxmaylsufWUdJmSvrP+vnUa2o4OyOe4BSWl8vzZweJ7iwxMKVrOdQ3KoP1 JDKnalW9qjsml44hvB3FWb0K+uhYZNTVB2Du9PQ5TLbeK6YJftXzUmnIysgEsyV9EwJE5Bd3vrhee cRVXKuPIyLOxslRLrBjexA==; Date: Sat, 31 May 2025 19:20:58 +0300 Message-Id: <86r004rbth.fsf@gnu.org> From: Eli Zaretskii To: Stefan Monnier In-Reply-To: (message from Stefan Monnier on Sat, 31 May 2025 10:56:19 -0400) Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. References: <86h611rqbh.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 78543 Cc: marcoxa@gmail.com, 78543@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Stefan Monnier > Cc: Marco Antoniotti , 78543@debbugs.gnu.org > Date: Sat, 31 May 2025 10:56:19 -0400 > > >> ``` > >> (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > >> "Do something with THAT (passed via :THIS)" > >> ... > >> ) > >> ``` > > FWIW, I consider this `(:this that)` of CL's keyword args to be > a misfeature, so I'm happy for Emacs to behave suboptimally here, tho > I'd prefer for cl-lib to stop supporting it. But do you have anything against the patch I proposed to install? > > Also, I believe that THE-BEAST should > > indeed be mentioned in the doc string. > > Why? It's not part of the function's exposed interface. > It's just a weird way to define a local variable. > > I also find this `&aux` thingy to be a misfeature in CL, which we > usually shouldn't support [ tho currently it's admittedly handy at > times in `cl-defstruct` constructors. ], so I'm not sure it's worth > complicating checkdoc for it. I didn't suggest complicating checkdoc due to &aux arguments. So we basically agree here. From debbugs-submit-bounces@debbugs.gnu.org Sat May 31 12:35:18 2025 Received: (at 78543) by debbugs.gnu.org; 31 May 2025 16:35:18 +0000 Received: from localhost ([127.0.0.1]:59307 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLPAy-0007DG-Eh for submit@debbugs.gnu.org; Sat, 31 May 2025 12:35:17 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:23765) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uLPAv-00078q-32 for 78543@debbugs.gnu.org; Sat, 31 May 2025 12:35:13 -0400 Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id E24418091B; Sat, 31 May 2025 12:29:38 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1748708977; bh=fLF0DHm4GxQP3o4B6WOvTfVIJxUzrgcVKStdGWnbGHE=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=e1NWgKtg2dPXPdXpnalTSFGm5Gi1BFK6YdLHHVfjYsBXFQFbAJJ7mRoYf2oEnmlIK yeI/tCCa741JCaUFpNtG27ngEhE+k6IqmzwHIAF0ugma1IpNMOj2CA6O9EvDRsFWKz Jv9+w9set2pUIDB8awVhsbKwP4youy5CPAPl6MNJWxrutYR0MLX8nPIVWMztMfyn0W Ss45yFOGnaLfUmvG8gst8EejlkiBgCi7grsx4OAn5udtixBEsDSTzHVMsIOXmkxhJU 16T2hCNd8BIeRCvzaV0QSPSa8GCxWVKiK2wqpR7188xeRm4hPDSCBcvb8wa7XDs7xG j2n+cYa06VS0Q== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 2056B803F6; Sat, 31 May 2025 12:29:37 -0400 (EDT) Received: from alfajor (unknown [104.247.225.139]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id B701512058B; Sat, 31 May 2025 12:29:36 -0400 (EDT) From: Stefan Monnier To: Eli Zaretskii Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. In-Reply-To: <86r004rbth.fsf@gnu.org> Message-ID: References: <86h611rqbh.fsf@gnu.org> <86r004rbth.fsf@gnu.org> Date: Sat, 31 May 2025 12:29:34 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL -0.374 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain DKIM_VALID_EF -0.1 Message has a valid DKIM or DK signature from envelope-from domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 78543 Cc: marcoxa@gmail.com, 78543@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) >> FWIW, I consider this `(:this that)` of CL's keyword args to be >> a misfeature, so I'm happy for Emacs to behave suboptimally here, tho >> I'd prefer for cl-lib to stop supporting it. > But do you have anything against the patch I proposed to install? I don't like the extra code in your patch to handle this special case, to be honest, but as long as we want to fully support this CL functionality, your patch looks fine. > I didn't suggest complicating checkdoc due to &aux arguments. > So we basically agree here. Indeed, we get to the same conclusion, tho via different paths. =F0=9F=99= =82 Stefan From debbugs-submit-bounces@debbugs.gnu.org Sat May 31 17:58:51 2025 Received: (at 78543) by debbugs.gnu.org; 31 May 2025 21:58:51 +0000 Received: from localhost ([127.0.0.1]:60927 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLUE6-0003eb-L2 for submit@debbugs.gnu.org; Sat, 31 May 2025 17:58:51 -0400 Received: from mail-yw1-x112d.google.com ([2607:f8b0:4864:20::112d]:39934) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1uLUE4-0003du-0C for 78543@debbugs.gnu.org; Sat, 31 May 2025 17:58:49 -0400 Received: by mail-yw1-x112d.google.com with SMTP id 00721157ae682-70834f92aaeso1440517b3.3 for <78543@debbugs.gnu.org>; Sat, 31 May 2025 14:58:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1748728722; x=1749333522; darn=debbugs.gnu.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=Tn/tB3DIEsMlZeqMPvVK6eHXZPs0PbdP0uBAcogmk0Y=; b=XWCUBdBHo+xuFwM8EKDRQ8hT1TSRzQqBlJvqqIGhOu4Ndm0i3OJvfLOhA9jMXS5JHu AxHRefQ9dbKDDzv1d7fqXlwYOzcfZmplBs0LX4K8o8FLx4L4SZ6ucbopiBQL+TnmOhva KhRPqddWj3NSpJQgpKc0NZRZJs/exG9N0fGC+GyJDQRKDAxYs/hdgq8PlV6vIefjBPXn zPsvSm7VbM3JgcIoMW25F450uq6GBC2GTjay/+y//VS6Ix3nooPwbgHiesNjgszpxB3+ 0L6cXcjutO/Fnd691SiIp9nBvXQBnBSniLe7iUQ9uj6TrQILr6ULUh2okBaDxrB+VCxw +Gig== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1748728722; x=1749333522; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Tn/tB3DIEsMlZeqMPvVK6eHXZPs0PbdP0uBAcogmk0Y=; b=rHcJHIyECgxEerfBQcxmro5rtcO93R3SYr+Nl6hGZ51tP1wn3eyrZ7ENMW284DWWsh wivdXJQrP7FJL4BnheheE8fVHs8sVsiQlmG1qU8BVDDoNfJirC99M8HSIE+HpBWjSt2d WcYi58GlwiEMvNQD15VLz5w9XBnFuwZ8uQWVkpln9shzKxnWnpKhiE9XDUexW6rS0u2B wcHZbNXckRJw8PjLUULDMLDboHekycpC4BubrCZZJJKRL0uIPkzjmZ0Aa17UTat4/qjq /CNHr5tpC0P30fErMxweQ+owRsf5RONDm6c065G7xTSQ7tomnrV+JsRsCyLBfW1Bw5pJ t7fA== X-Forwarded-Encrypted: i=1; AJvYcCWuwKjdFkCODj73rRXsgIUCFXHCKxl3iPwEpWD4fI/LOdPeSS1iG5A+x2RaqdqQqMEeU96lGA==@debbugs.gnu.org X-Gm-Message-State: AOJu0YzUBUCJ2nF2c9ABuJonEog8G8feNw6gHpVODvnbUYvHOmLziSgI FDrW+hTqr9iGkJlmQqRPi85N0aMvH9Zyd3UxhYKE4UXmOG7xyMmdSiXFejnLNpLdo6zMPjj+ef3 F397J4MPW6chxZk8lWZTPYIY0OL3I6bQ= X-Gm-Gg: ASbGncukwiuSzo4/qJSpU19GwhZhSft+LiXNo3EcdoFaQUCtihxfL5ofO5X36Zy8Hzb Y2LBCI0KHruQrNvqNkXJMC+TA+yJ4EeXJmJPBmTQpZa0efamHbEEsifRG198rOOhZ7oXZMOwI+9 Wue0o1j7cT+ZlGZ/ovoAwYrcm//u795xjbxQKB/Q1MruQ= X-Google-Smtp-Source: AGHT+IF1Ui6ooIbLjUzKvZRdX/ljlAkEG/BCq0UI4ryIkkiUSvne6uTJMYVbQ/KNa9GCbGi4mKmNySNDrlGgXo/Ukfs= X-Received: by 2002:a05:690c:7002:b0:70f:751c:2d9d with SMTP id 00721157ae682-71048cbaa06mr47460097b3.4.1748728722182; Sat, 31 May 2025 14:58:42 -0700 (PDT) MIME-Version: 1.0 References: <86h611rqbh.fsf@gnu.org> In-Reply-To: <86h611rqbh.fsf@gnu.org> From: Marco Antoniotti Date: Sat, 31 May 2025 23:58:26 +0200 X-Gm-Features: AX0GCFt_Ap_PUi5ERiR0ezx7gnmVR_1sMytS-1EpUxpITw_BMBIc_B7nR4uAgXw Message-ID: Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. To: Eli Zaretskii Content-Type: multipart/alternative; boundary="0000000000004b580c063675a2bc" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 78543 Cc: 78543@debbugs.gnu.org, Stefan Monnier X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --0000000000004b580c063675a2bc Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi... On Sat, May 31, 2025 at 1:07=E2=80=AFPM Eli Zaretskii wrote: > > From: Marco Antoniotti > > Date: Wed, 21 May 2025 22:38:48 +0200 > > > > The problem is with `checkdoc` not correctly handling some docstring > > in `cl-lib` style declarations. > > > > I have a function like > > > > ``` > > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > > "Do something with THAT (passed via :THIS)" > > ... > > ) > > ``` > > > > checkdoc insists on flagging :THIS and THE-BEAST as missing from the > docstring. > > > > Another one is the following. > > > > ``` > > (cl-defgeneric gf (a s d f) > > (:documentation "Munge A, S, D, and F.")) > > ``` > > > > checkdoc does not recognize the :documentation option (which is valid > according to cl-lib). > > > > This problem is still visible in 30.1 > > Sigh. This is notoriously under-documented in the cl.info manual. > After reading and re-reading the node "Argument Lists" there, I > believe that we expect :this to be referenced as "THIS" (without the > leading colon) in the doc string, since argument references in doc > strings should be words, not symbols, and ':' is not a > word-constituent character. Also, I believe that THE-BEAST should > indeed be mentioned in the doc string. This: > > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > "Do something with THAT (passed via THIS), binding THE-BEAST to 666= ." > nil > ) > > passes the checkdoc tests, if we install the simple patch below. > > But since I'm very far from being an expert of cl-defun and its > correct usage, I invite CL experts to chime in and provide their > opinions. > The problem shows up even if you use THIS without a colon (without the patch, I mean). THE-BEAST should NOT be flagged as it is definitively not part of the function signature. &aux variables should be ignored for doc strings. Any update on the cl-defgeneric :documentation slot? My 2 cents: Yes Emacs Lisp should support CL idioms. CL got many things right in the base language (yes Virginia! I know about pathnames :) ). All the best --=20 Marco Antoniotti Somewhere over the Rainbow --0000000000004b580c063675a2bc Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi...

On Sat, May 31, 2025 at 1:= 07=E2=80=AFPM Eli Zaretskii <eliz@gnu.or= g> wrote:
> From: Marco Antoniotti <marcoxa@gmail.com>
> Date: Wed, 21 May 2025 22:38:48 +0200
>
> The problem is with `checkdoc` not correctly handling some docstring > in `cl-lib` style declarations.
>
> I have a function like
>
> ```
> (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 6= 66))
>=C2=A0 =C2=A0 =C2=A0"Do something with THAT (passed via :THIS)&quo= t;
>=C2=A0 =C2=A0 =C2=A0...
>=C2=A0 =C2=A0 =C2=A0)
> ```
>
> checkdoc insists on flagging :THIS and THE-BEAST as missing from the d= ocstring.
>
> Another one is the following.
>
> ```
> (cl-defgeneric gf (a s d f)
>=C2=A0 =C2=A0 =C2=A0(:documentation "Munge A, S, D, and F."))=
> ```
>
> checkdoc does not recognize the :documentation option (which is valid = according to cl-lib).
>
> This problem is still visible in 30.1

Sigh.=C2=A0 This is notoriously under-documented in the cl.info manual.
After reading and re-reading the node "Argument Lists" there, I believe that we expect :this to be referenced as "THIS" (without = the
leading colon) in the doc string, since argument references in doc
strings should be words, not symbols, and ':' is not a
word-constituent character.=C2=A0 Also, I believe that THE-BEAST should
indeed be mentioned in the doc string.=C2=A0 This:

=C2=A0 (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast= 666))
=C2=A0 =C2=A0 =C2=A0 "Do something with THAT (passed via THIS), bindin= g THE-BEAST to 666."
=C2=A0 =C2=A0 =C2=A0 nil
=C2=A0 =C2=A0 =C2=A0 )

passes the checkdoc tests, if we install the simple patch below.

But since I'm very far from being an expert of cl-defun and its
correct usage, I invite CL experts to chime in and provide their
opinions.

The problem shows up even if = you use THIS without a colon (without the patch, I mean).

THE-BEAST should NOT be flagged as it is definitively not part of t= he function signature.=C2=A0 &aux variables should be ignored for doc s= trings.

Any update on the cl-defgeneric :documenta= tion slot?

My 2 cents:=C2=A0 Yes Emacs Lisp should suppor= t CL idioms.=C2=A0 CL got many things right in the base language (yes Virgi= nia! I know about pathnames :) ).

All the best
--
Marco Antoniotti
Somewhere over the R= ainbow
--0000000000004b580c063675a2bc-- From debbugs-submit-bounces@debbugs.gnu.org Sun Jun 01 01:39:03 2025 Received: (at 78543) by debbugs.gnu.org; 1 Jun 2025 05:39:04 +0000 Received: from localhost ([127.0.0.1]:35376 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLbPQ-0000aE-TR for submit@debbugs.gnu.org; Sun, 01 Jun 2025 01:39:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52674) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uLbPK-0000Z6-L2 for 78543@debbugs.gnu.org; Sun, 01 Jun 2025 01:38:58 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uLbPE-0006UH-J3; Sun, 01 Jun 2025 01:38:48 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=1EaXKKt9rhMZA+1y8xe8bvDNzI/SybtvgdZvW7/rYPo=; b=MIwu8fGkzanq m8hk8/bCKN188BO/pHCodIy/ntCTUMDpYcp1uiVKOQL4aRPQlMa1DGTrIKUzl0vKBOxNdG8Om3q/C Wjut9dXRMFk2S4AdCgXdIryOfKGcgBMcvLw53HlPwnocAJ9Mrvs7Kyma/064wdZzQg3EkD9oCsg3M zQfPRWUARJ1UNvW9oV6fEMq/i7EhUq+UPlNvG1fXYpJPM9TAM07PAtxzd4Q2DVWFYePChv6L2QlQ2 YZuw07vD93XT7NM1hjNzreT6P4xwxOcHA2NW5KR5fHTayjHIwd//O8RH+kwhdwbl/RFc2Zlv5oFOy 7gTsj7k91Id/X1WHJCc+Lw==; Date: Sun, 01 Jun 2025 08:38:43 +0300 Message-Id: <86ecw4qavw.fsf@gnu.org> From: Eli Zaretskii To: Marco Antoniotti In-Reply-To: (message from Marco Antoniotti on Sat, 31 May 2025 23:58:26 +0200) Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. References: <86h611rqbh.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 78543 Cc: 78543@debbugs.gnu.org, monnier@iro.umontreal.ca X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Marco Antoniotti > Date: Sat, 31 May 2025 23:58:26 +0200 > Cc: Stefan Monnier , 78543@debbugs.gnu.org > > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > "Do something with THAT (passed via THIS), binding THE-BEAST to 666." > nil > ) > > passes the checkdoc tests, if we install the simple patch below. > > But since I'm very far from being an expert of cl-defun and its > correct usage, I invite CL experts to chime in and provide their > opinions. > > The problem shows up even if you use THIS without a colon (without the patch, I mean). Yes, like I said. Does the patch fix it for you? > THE-BEAST should NOT be flagged as it is definitively not part of the function signature. &aux variables > should be ignored for doc strings. I disagree. If they should be ignored, why use them at all? My assumption is that if you use them, they are important, so should be documented. The doc string is not only about the function's signature, it's about anything that's important to know about the function. > Any update on the cl-defgeneric :documentation slot? Is this related, or is this a separate issue? Do we have a separate bug report for it? From debbugs-submit-bounces@debbugs.gnu.org Sun Jun 01 03:52:35 2025 Received: (at 78543) by debbugs.gnu.org; 1 Jun 2025 07:52:35 +0000 Received: from localhost ([127.0.0.1]:36199 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uLdUf-0000Y4-0v for submit@debbugs.gnu.org; Sun, 01 Jun 2025 03:52:35 -0400 Received: from mail-yb1-xb2b.google.com ([2607:f8b0:4864:20::b2b]:40580) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1uLdUa-0000Wz-Uy for 78543@debbugs.gnu.org; Sun, 01 Jun 2025 03:52:31 -0400 Received: by mail-yb1-xb2b.google.com with SMTP id 3f1490d57ef6-e7dc7245bcdso429043276.2 for <78543@debbugs.gnu.org>; Sun, 01 Jun 2025 00:52:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1748764343; x=1749369143; darn=debbugs.gnu.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=FyNckvfI6yYdcQhUTJFVEgPiUskYroG+k4FG4REiTzc=; b=XC4XiJsH7/0QVuc7DYB2G+3wWwDeL2mX+hp0fpVDd6bOaoAnZR9RB8tWS1EauApALI DDlekljyZBCyL0gjMc/Sg1kxNl6MUX4e0XrGOLf50pVW0TAPQpHkfssw7MV9g4BLvVvx iySrjdHZ/exr3e+cA3It8wD38Z5BIsbvjf8Wa0yTEsogZEltrZyyPK4tdP5VHgiag+Ct +B6yS0LnvQqxFoildlVVz3EU4CjJzgy9vyI3dXSEZ7V11UQLyRnTumP1Z+EYO8zW2ICZ u2FWooR3Yhe/v2LRgCQxNZWX9Mhw8psbtU/nCbukDG2Wh87AG7usc8X1M4WdjEu453Pa WOAQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1748764343; x=1749369143; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=FyNckvfI6yYdcQhUTJFVEgPiUskYroG+k4FG4REiTzc=; b=YZvp5tMKjczmhCIxC1+GA7NIOkJGaACRnd4O7vaDIeMuecVc20ISItkmIsRO6HDSXB 89Uf/ywF1Yxq9tnblu3u+yl5X0hlui97LT4GoFtzM1tXI7FN4aiZw5nPR2dyeJWfDxS1 bBwBAald4ewerAr1Vn4Oe18CLJw9nYUdM7x8INIDkVHYKJFI+HxFNSNgPFhuWTR/lG1H 0DPAKNjp375fOPQ3iLMJ98PPlkmzoKnQj02cenUJpObexQVX9Wl+XA9fp+a816zKZJkT ugm4hkTtQkXPzOM0yVkLs54N9UNJJbosTV+w5vDnOLLVxtHSgwrPJFYzie7aV+aqYlvq 4txw== X-Forwarded-Encrypted: i=1; AJvYcCWj0zpWK7cdJOWIjvMAWVppvC+sHeUyg1qhqF9lU8gKpRGy6sv/96f4YmYWNgFj0Xs9J2BHvg==@debbugs.gnu.org X-Gm-Message-State: AOJu0YywSiWX1+pjPc3j/lTXc4SwaAoSS4sCpim5ewJqnCIlH0BmAKoL JgR29yydlKdrktVYFxFkP114f4pp5NCSUpAj7eHBQgjD/sG39iMLcOMzWmXA/vFeSHsyzgrH75e Zgp/qdDwbcK0Uvk4m+W5xBJMfulAXhbc= X-Gm-Gg: ASbGnctfsFdajlMTZjsiG1ZNI1lsQ3NcT+xurvhbzbPPBREAvBgVpfHZMkltapmb4De a2mJHKcoF80uavbzoATxwa6/v3x58UD/UB4cY5NzZKuHdfzuMfFS6N6X6u7DK2uLF1VWgfhviJD XpCBT5kJplsmMqH70pZXmM6Bq+NAF8l8sq X-Google-Smtp-Source: AGHT+IETUO9litScJ9TuKBh2hUbj+CCgQcyKLxYSdxjx3FI1JeO9gbBuw8q3nWOToEhvgUH+rZTJTwnqfqYaRMNNoaw= X-Received: by 2002:a05:6902:1142:b0:e7d:b52c:6637 with SMTP id 3f1490d57ef6-e7f8640493amr4443266276.0.1748764343109; Sun, 01 Jun 2025 00:52:23 -0700 (PDT) MIME-Version: 1.0 References: <86h611rqbh.fsf@gnu.org> <86ecw4qavw.fsf@gnu.org> In-Reply-To: <86ecw4qavw.fsf@gnu.org> From: Marco Antoniotti Date: Sun, 1 Jun 2025 09:52:11 +0200 X-Gm-Features: AX0GCFtXOVfkDeXczOHy9Q0LMHHotvPt2W5hfFc-Bi9LMsQhyBx5YpqSSWPq04o Message-ID: Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. To: Eli Zaretskii Content-Type: multipart/alternative; boundary="000000000000778f5306367ded86" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 78543 Cc: 78543@debbugs.gnu.org, monnier@iro.umontreal.ca X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --000000000000778f5306367ded86 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Sun, Jun 1, 2025 at 7:38=E2=80=AFAM Eli Zaretskii wrote: > > From: Marco Antoniotti > > Date: Sat, 31 May 2025 23:58:26 +0200 > > Cc: Stefan Monnier , 78543@debbugs.gnu.org > > > > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > > "Do something with THAT (passed via THIS), binding THE-BEAST to > 666." > > nil > > ) > > > > passes the checkdoc tests, if we install the simple patch below. > > > > But since I'm very far from being an expert of cl-defun and its > > correct usage, I invite CL experts to chime in and provide their > > opinions. > > > > The problem shows up even if you use THIS without a colon (without the > patch, I mean). > > Yes, like I said. Does the patch fix it for you? > I have not checked the patch. Sorry. I assume it works, although I am inclined to allow :THIS in the doc string. After all that is the signature of the function. > THE-BEAST should NOT be flagged as it is definitively not part of the > function signature. &aux variables > > should be ignored for doc strings. > > I disagree. If they should be ignored, why use them at all? My > assumption is that if you use them, they are important, so should be > documented. The doc string is not only about the function's > signature, it's about anything that's important to know about the > function. > The assumption of the CL programmer (well, I believe most of them, all 42 of them) is that they are a convenience (with possible optimization effects) mostly used to avoid a top level LET. If you go down that line of thought then you may end up wanting checkdoc to do the following. (cl-defun foo (x &aux (y (+ 42 x)) "Use X and Y. But, `checkdoc' forces me to tell you about THE-ANSWER." (let ((the-answer (- y x))) .... )) That is why &aux should be ignored by checkdoc. > Any update on the cl-defgeneric :documentation slot? > > Is this related, or is this a separate issue? Do we have a separate > bug report for it? > Same bug report a bit below the &key/&aux lambda list issue. Cheers --=20 Marco Antoniotti Somewhere over the Rainbow --000000000000778f5306367ded86 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Sun, Jun 1, = 2025 at 7:38=E2=80=AFAM Eli Zaretskii <e= liz@gnu.org> wrote:
> From: Marco Antoniotti <marcoxa@gmail.com>
> Date: Sat, 31 May 2025 23:58:26 +0200
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, 78543@debbugs.gnu.org
>
>=C2=A0 =C2=A0 (cl-defun funky-keys (&key ((:this that) 42) &aux= (the-beast 666))
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 "Do something with THAT (passed via TH= IS), binding THE-BEAST to 666."
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 nil
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 )
>
>=C2=A0 passes the checkdoc tests, if we install the simple patch below.=
>
>=C2=A0 But since I'm very far from being an expert of cl-defun and = its
>=C2=A0 correct usage, I invite CL experts to chime in and provide their=
>=C2=A0 opinions.
>
> The problem shows up even if you use THIS without a colon (without the= patch, I mean).

Yes, like I said.=C2=A0 Does the patch fix it for you?


I have not checked the patch.=C2=A0 Sorry.= =C2=A0 I assume it works, although I am inclined to allow :THIS in the doc string.
After all th= at is the signature of the function.


> THE-BEAST should NOT be flagged as it is definitively not part of the = function signature.=C2=A0 &aux variables
> should be ignored for doc strings.

I disagree.=C2=A0 If they should be ignored, why use them at all?=C2=A0 My<= br> assumption is that if you use them, they are important, so should be
documented.=C2=A0 The doc string is not only about the function's
signature, it's about anything that's important to know about the function.

The assumption of the CL prog= rammer (well, I believe most of them, all 42 of them) is that they are a co= nvenience (with possible optimization
effects) mostly used to avo= id a top level LET.=C2=A0 If you go down that line of thought then you may = end up wanting checkdoc to do the following.

(cl-defun foo (x &aux (y (+ 42 x))
=
=C2=A0=C2=A0 "= Use X and Y.=C2=A0 But, `checkdoc' forces me to tell you about THE-ANSW= ER."
=C2=A0=C2= =A0 (let ((the-answer (- y x)))
=C2=A0=C2=A0 ....
))

That is= why &aux should be ignored by checkdoc.

> Any update on the cl-defgeneric :documentation slot?

Is this related, or is this a separate issue?=C2=A0 Do we have a separate bug report for it?

Same bug report a bi= t below the &key/&aux lambda list issue.

Cheers
-- =
Marco Antoniotti
Somewher= e over the Rainbow
--000000000000778f5306367ded86-- From debbugs-submit-bounces@debbugs.gnu.org Sat Jun 07 05:18:49 2025 Received: (at 78543-done) by debbugs.gnu.org; 7 Jun 2025 09:18:49 +0000 Received: from localhost ([127.0.0.1]:46898 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uNphQ-00020F-Vj for submit@debbugs.gnu.org; Sat, 07 Jun 2025 05:18:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36056) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uNphN-0001zy-MQ for 78543-done@debbugs.gnu.org; Sat, 07 Jun 2025 05:18:46 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uNphI-0000hJ-2U; Sat, 07 Jun 2025 05:18:40 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=fh3YBsYDYedCVxwkIaYGbF1KTM14tHEI1h5DbqQhX+k=; b=aRM/u8/7BtK68Surk0yU 8ro/KK9gM1wqebQP2vpUdL6WsT6F7aLjdlZbX0AYru2wTNM06TbP8NAdnEKrseNsn2vrB8LsOhQMO x8vVCy18jL5Y2PER5Zq+C7LsFvROkZLCcfIMh4ugEPsGFQ8dr23bHN9laiSoHDyz/XZfcwlbq1k2A E/sQQAlmAXr9ctSp5mAK2MUa6SEsXW8G8TrYNamjy2czW4lEHD6asQD55QWzerS29ew4oTokbsyAh KrRhRKHH0OqtBYfy/wn0Admm42YYqn9qnvVIVbvZODpNeqLiHpUXuVWTWex+RM+PfCOYFY/tbBi8E wAwtrBHvr6Za4Q==; Date: Sat, 07 Jun 2025 12:18:35 +0300 Message-Id: <86h60rj4es.fsf@gnu.org> From: Eli Zaretskii To: Marco Antoniotti In-Reply-To: (message from Marco Antoniotti on Sun, 1 Jun 2025 09:52:11 +0200) Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. References: <86h611rqbh.fsf@gnu.org> <86ecw4qavw.fsf@gnu.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 78543-done Cc: 78543-done@debbugs.gnu.org, monnier@iro.umontreal.ca X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Marco Antoniotti > Date: Sun, 1 Jun 2025 09:52:11 +0200 > Cc: monnier@iro.umontreal.ca, 78543@debbugs.gnu.org > > On Sun, Jun 1, 2025 at 7:38 AM Eli Zaretskii wrote: > > > From: Marco Antoniotti > > Date: Sat, 31 May 2025 23:58:26 +0200 > > Cc: Stefan Monnier , 78543@debbugs.gnu.org > > > > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)) > > "Do something with THAT (passed via THIS), binding THE-BEAST to 666." > > nil > > ) > > > > passes the checkdoc tests, if we install the simple patch below. > > > > But since I'm very far from being an expert of cl-defun and its > > correct usage, I invite CL experts to chime in and provide their > > opinions. > > > > The problem shows up even if you use THIS without a colon (without the patch, I mean). > > Yes, like I said. Does the patch fix it for you? > > I have not checked the patch. Sorry. I assume it works, although I am inclined to allow :THIS in the doc > string. > After all that is the signature of the function. > > > THE-BEAST should NOT be flagged as it is definitively not part of the function signature. &aux > variables > > should be ignored for doc strings. > > I disagree. If they should be ignored, why use them at all? My > assumption is that if you use them, they are important, so should be > documented. The doc string is not only about the function's > signature, it's about anything that's important to know about the > function. > > The assumption of the CL programmer (well, I believe most of them, all 42 of them) is that they are a > convenience (with possible optimization > effects) mostly used to avoid a top level LET. If you go down that line of thought then you may end up > wanting checkdoc to do the following. > > (cl-defun foo (x &aux (y (+ 42 x)) > "Use X and Y. But, `checkdoc' forces me to tell you about THE-ANSWER." > (let ((the-answer (- y x))) > .... > )) > > That is why &aux should be ignored by checkdoc. Thanks, but I don't think I agree. I've now installed the patch I proposed up-thread, and I'm closing this bug. From debbugs-submit-bounces@debbugs.gnu.org Sat Jun 07 05:54:26 2025 Received: (at 78543-done) by debbugs.gnu.org; 7 Jun 2025 09:54:26 +0000 Received: from localhost ([127.0.0.1]:46992 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uNqFt-0003uh-Df for submit@debbugs.gnu.org; Sat, 07 Jun 2025 05:54:25 -0400 Received: from mail-yb1-xb2d.google.com ([2607:f8b0:4864:20::b2d]:39808) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from ) id 1uNqFr-0003uL-3b for 78543-done@debbugs.gnu.org; Sat, 07 Jun 2025 05:54:23 -0400 Received: by mail-yb1-xb2d.google.com with SMTP id 3f1490d57ef6-e7dae2a8121so348437276.3 for <78543-done@debbugs.gnu.org>; Sat, 07 Jun 2025 02:54:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1749290057; x=1749894857; darn=debbugs.gnu.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=XDz269pX3H0Kh6zfYjU6U3iLC8siBQ1iXqoiOXEOpic=; b=Ubto1VahTdVxqqbXsMeJmybO/qhyOHzvJsrrVmQmdGiZGJfpKlMEsv6J2vJXEpphyB sVsjw2Z/hqJEbNTBxOt3dcvGjt5XuVC8kM8OZvD505PJJ8bD6FZHASt8KGI63y9jCZjL uKItXAh173xElIRL11OR4iHFVj89GIFTw2IQDGLI43GtvEgdYO6ONItzMCZDetWnaJ18 yyYQjh++GozxHZ8yYwdcyGEoUVrULNCX9NkcGWQeUjsa6uQZW0Eqjy1YsP14bfkLgWkN Tq4HMMVGpg+7coYoHKTpGuSa7SdTtQthP/61gwGf456u9ibhPzeVWmsZhXFYRfU4fhJU Pklg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1749290057; x=1749894857; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=XDz269pX3H0Kh6zfYjU6U3iLC8siBQ1iXqoiOXEOpic=; b=lcppxk2kFIUocZ2QEI+KN/20Dy8eyk+ADLJikMDZIGj9K0Gkb17d06qsO8xKCLKjML jmbUifDv09XiKE14wG2Ub1NZw82pqcsPBgGsxS3BgRepo33j3jpnxywBZoHUMg8PEADY 8pBePKGUST5EhhRi1xLjhzoARSLUg+4NRr93elVdPAzXUGVFz+20A5bJh51JNbwN8Fyy nA+mQ7qPgfqkuJ+Vvrm95RlJ15UAbv77gVWU9CKWTSuhXxT/59lsRwUacFAQGcNJy599 ds2uzdXqgrlzT+KCYxsIgD0e2v7FhoG1o/m8oQDJMNbcIYj/stsYybMJtjRIFXEmIgU/ Toig== X-Forwarded-Encrypted: i=1; AJvYcCW/mR34/X4T0N6r48pllyFAKIOPUNC8U2i3tNhkhAoJKByQWL5zWQp3eBeP4urmf7QRhuyBbN+zMpkh@debbugs.gnu.org X-Gm-Message-State: AOJu0YwGvpI32izpayPRbuA5zGDa7hTUofons7EqNNcYBYi0YW3FEEfS m8lidwNukyP/1HaV9I8s5bBqvo1e9QHI5kt7w0LguGo7/r/C0XIr7OKilSozGolAVgHcsx3I9Bv 7ILUIVAsGrin2Pvqgaz528hPcZhfAyGk= X-Gm-Gg: ASbGncv92XbngG5RRAq6Yy4EyXsJGX8MuyBTHgAVfwuS0vubXAPjRPRJFkcjYS4jt4G StfcNMjjvOS8lDJlcoONABZ/8GLtG1N6EQWUPMKvzmaTU/B/ulNI5IVaPvn4p2sjl7TgKTQegm6 3f+r/WMKJp84RucSNbg15lZKgc+HUe/QwglUrqqfjXydQyUjYI5EYJuw== X-Google-Smtp-Source: AGHT+IHLTWXiwZzL5rd1Txh4DP8UKXSBhIA77MJV9AyF4Mj79IkfGdk38rFGFIZjmEGI8h5CSsd8F78IlPKEZiJ8Oio= X-Received: by 2002:a05:6902:1886:b0:e81:57f6:4dab with SMTP id 3f1490d57ef6-e81a9170220mr3276675276.2.1749290057394; Sat, 07 Jun 2025 02:54:17 -0700 (PDT) MIME-Version: 1.0 References: <86h611rqbh.fsf@gnu.org> <86ecw4qavw.fsf@gnu.org> <86h60rj4es.fsf@gnu.org> In-Reply-To: <86h60rj4es.fsf@gnu.org> From: Marco Antoniotti Date: Sat, 7 Jun 2025 11:54:04 +0200 X-Gm-Features: AX0GCFuDgPKkgOmPBlETy9twctq-GL-o3IRG1ksl6Q55d21S3QdWoWWbnGxccfI Message-ID: Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. To: Eli Zaretskii Content-Type: multipart/alternative; boundary="0000000000007aedfb0636f8540c" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 78543-done Cc: 78543-done@debbugs.gnu.org, monnier@iro.umontreal.ca X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --0000000000007aedfb0636f8540c Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi you mean you are willing to go against the collective will of the CL Community at large? =F0=9F=A5=B9=F0=9F=98=8F=F0=9F=98=81=F0=9F=98=91 On Sat, Jun 7, 2025 at 11:18=E2=80=AFAM Eli Zaretskii wrote: > > From: Marco Antoniotti > > Date: Sun, 1 Jun 2025 09:52:11 +0200 > > Cc: monnier@iro.umontreal.ca, 78543@debbugs.gnu.org > > > > On Sun, Jun 1, 2025 at 7:38=E2=80=AFAM Eli Zaretskii wro= te: > > > > > From: Marco Antoniotti > > > Date: Sat, 31 May 2025 23:58:26 +0200 > > > Cc: Stefan Monnier , 78543@debbugs.gnu.org > > > > > > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666)= ) > > > "Do something with THAT (passed via THIS), binding THE-BEAST > to 666." > > > nil > > > ) > > > > > > passes the checkdoc tests, if we install the simple patch below. > > > > > > But since I'm very far from being an expert of cl-defun and its > > > correct usage, I invite CL experts to chime in and provide their > > > opinions. > > > > > > The problem shows up even if you use THIS without a colon (without > the patch, I mean). > > > > Yes, like I said. Does the patch fix it for you? > > > > I have not checked the patch. Sorry. I assume it works, although I am > inclined to allow :THIS in the doc > > string. > > After all that is the signature of the function. > > > > > THE-BEAST should NOT be flagged as it is definitively not part of th= e > function signature. &aux > > variables > > > should be ignored for doc strings. > > > > I disagree. If they should be ignored, why use them at all? My > > assumption is that if you use them, they are important, so should be > > documented. The doc string is not only about the function's > > signature, it's about anything that's important to know about the > > function. > > > > The assumption of the CL programmer (well, I believe most of them, all > 42 of them) is that they are a > > convenience (with possible optimization > > effects) mostly used to avoid a top level LET. If you go down that lin= e > of thought then you may end up > > wanting checkdoc to do the following. > > > > (cl-defun foo (x &aux (y (+ 42 x)) > > "Use X and Y. But, `checkdoc' forces me to tell you about > THE-ANSWER." > > (let ((the-answer (- y x))) > > .... > > )) > > > > That is why &aux should be ignored by checkdoc. > > Thanks, but I don't think I agree. > > I've now installed the patch I proposed up-thread, and I'm closing > this bug. > --=20 Marco Antoniotti Somewhere over the Rainbow --0000000000007aedfb0636f8540c Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi

you mean you are willing = to go against the collective will of the CL Community at large? =F0=9F=A5= =B9=F0=9F=98=8F=F0=9F=98=81=F0=9F=98=91

On S= at, Jun 7, 2025 at 11:18=E2=80=AFAM Eli Zaretskii <eliz@gnu.org> wrote:
> From: Marco Antoniotti <marcoxa@gmail.com>
> Date: Sun, 1 Jun 2025 09:52:11 +0200
> Cc: monn= ier@iro.umontreal.ca, 78543@debbugs.gnu.org
>
> On Sun, Jun 1, 2025 at 7:38=E2=80=AFAM Eli Zaretskii <eliz@gnu.org> wrote:
>
>=C2=A0 > From: Marco Antoniotti <marcoxa@gmail.com>
>=C2=A0 > Date: Sat, 31 May 2025 23:58:26 +0200
>=C2=A0 > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, 78543@debbugs.gnu.org
>=C2=A0 >
>=C2=A0 >=C2=A0 =C2=A0 (cl-defun funky-keys (&key ((:this that) 4= 2) &aux (the-beast 666))
>=C2=A0 >=C2=A0 =C2=A0 =C2=A0 =C2=A0 "Do something with THAT (pa= ssed via THIS), binding THE-BEAST to 666."
>=C2=A0 >=C2=A0 =C2=A0 =C2=A0 =C2=A0 nil
>=C2=A0 >=C2=A0 =C2=A0 =C2=A0 =C2=A0 )
>=C2=A0 >
>=C2=A0 >=C2=A0 passes the checkdoc tests, if we install the simple p= atch below.
>=C2=A0 >
>=C2=A0 >=C2=A0 But since I'm very far from being an expert of cl= -defun and its
>=C2=A0 >=C2=A0 correct usage, I invite CL experts to chime in and pr= ovide their
>=C2=A0 >=C2=A0 opinions.
>=C2=A0 >
>=C2=A0 > The problem shows up even if you use THIS without a colon (= without the patch, I mean).
>
>=C2=A0 Yes, like I said.=C2=A0 Does the patch fix it for you?
>
> I have not checked the patch.=C2=A0 Sorry.=C2=A0 I assume it works, al= though I am inclined to allow :THIS in the doc
> string.
> After all that is the signature of the function.
>
>=C2=A0 > THE-BEAST should NOT be flagged as it is definitively not p= art of the function signature.=C2=A0 &aux
>=C2=A0 variables
>=C2=A0 > should be ignored for doc strings.
>
>=C2=A0 I disagree.=C2=A0 If they should be ignored, why use them at all= ?=C2=A0 My
>=C2=A0 assumption is that if you use them, they are important, so shoul= d be
>=C2=A0 documented.=C2=A0 The doc string is not only about the function&= #39;s
>=C2=A0 signature, it's about anything that's important to know = about the
>=C2=A0 function.
>
> The assumption of the CL programmer (well, I believe most of them, all= 42 of them) is that they are a
> convenience (with possible optimization
> effects) mostly used to avoid a top level LET.=C2=A0 If you go down th= at line of thought then you may end up
> wanting checkdoc to do the following.
>
> (cl-defun foo (x &aux (y (+ 42 x))
>=C2=A0 =C2=A0 "Use X and Y.=C2=A0 But, `checkdoc' forces me to= tell you about THE-ANSWER."
>=C2=A0 =C2=A0 (let ((the-answer (- y x)))
>=C2=A0 =C2=A0 ....
> ))
>
> That is why &aux should be ignored by checkdoc.

Thanks, but I don't think I agree.

I've now installed the patch I proposed up-thread, and I'm closing<= br> this bug.


--
Ma= rco Antoniotti
Somewhere over the Rainbow
--0000000000007aedfb0636f8540c-- From debbugs-submit-bounces@debbugs.gnu.org Sun Jun 08 00:23:22 2025 Received: (at submit) by debbugs.gnu.org; 8 Jun 2025 04:23:22 +0000 Received: from localhost ([127.0.0.1]:50327 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uO7Z4-00057M-18 for submit@debbugs.gnu.org; Sun, 08 Jun 2025 00:23:22 -0400 Received: from lists.gnu.org ([2001:470:142::17]:59962) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uO7Z0-000574-Vb for submit@debbugs.gnu.org; Sun, 08 Jun 2025 00:23:20 -0400 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 1uO7Yv-00062A-7Q for bug-gnu-emacs@gnu.org; Sun, 08 Jun 2025 00:23:13 -0400 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 1uO7Yt-0000dU-8L for bug-gnu-emacs@gnu.org; Sun, 08 Jun 2025 00:23:12 -0400 Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1uO7Yp-0005FG-DA for bug-gnu-emacs@gnu.org; Sun, 08 Jun 2025 06:23:07 +0200 X-Injected-Via-Gmane: http://gmane.org/ To: bug-gnu-emacs@gnu.org From: Rudolf Schlatte Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs. Date: Sun, 08 Jun 2025 06:23:02 +0200 Message-ID: References: <86h611rqbh.fsf@gnu.org> <86ecw4qavw.fsf@gnu.org> <86h60rj4es.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit User-Agent: Gnus/5.13 (Gnus v5.13) Cancel-Lock: sha1:hNBsbzjBtMu9R5mR7nmvC8HHeis= Received-SPF: pass client-ip=116.202.254.214; envelope-from=geb-bug-gnu-emacs@m.gmane-mx.org; helo=ciao.gmane.io 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, HEADER_FROM_DIFFERENT_DOMAINS=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Marco Antoniotti writes: > you mean you are willing to go against the collective will of the CL Community > at large? 🥹😏😁😑 If the checkdoc nagging motivates someone to replace an &aux binding with a let form, I'd count that as an overall win. ;)