On Sun, Jun 1, 2025 at 7:38 AM Eli Zaretskii <
eliz@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
>
> (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.