GNU bug report logs -
#78543
29.2; checkdoc misses some CL (cl-lib) constructs.
Previous Next
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your bug report
#78543: 29.2; checkdoc misses some CL (cl-lib) constructs.
which was filed against the emacs package, has been closed.
The explanation is attached below, along with your original report.
If you require more details, please reply to 78543 <at> debbugs.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>
> 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.
[Message part 3 (message/rfc822, inline)]
[Message part 4 (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 5 (text/html, inline)]
This bug report was last modified 11 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.