GNU bug report logs - #78543
29.2; checkdoc misses some CL (cl-lib) constructs.

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#78543: closed (29.2; checkdoc misses some CL (cl-lib)
 constructs.)
Date: Sat, 07 Jun 2025 09:19:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Sat, 07 Jun 2025 12:18:35 +0300
with message-id <86h60rj4es.fsf <at> gnu.org>
and subject line Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs.
has caused the debbugs.gnu.org bug report #78543,
regarding 29.2; checkdoc misses some CL (cl-lib) constructs.
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
78543: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=78543
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Marco Antoniotti <marcoxa <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.2; checkdoc misses some CL (cl-lib) constructs.
Date: Wed, 21 May 2025 22:38:48 +0200

[Message part 3 (text/plain, inline)]

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

[Message part 4 (text/html, inline)]

[Message part 5 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Marco Antoniotti <marcoxa <at> gmail.com>
Cc: 78543-done <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs.
Date: Sat, 07 Jun 2025 12:18:35 +0300

> From: Marco Antoniotti <marcoxa <at> gmail.com>
> Date: Sun, 1 Jun 2025 09:52:11 +0200
> Cc: monnier <at> iro.umontreal.ca, 78543 <at> debbugs.gnu.org
> 
> On Sun, Jun 1, 2025 at 7:38 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
>  > From: Marco Antoniotti <marcoxa <at> gmail.com>
>  > Date: Sat, 31 May 2025 23:58:26 +0200
>  > Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 78543 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.