Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs.

From: Marco Antoniotti <[email-masked]>
Date: Sun, 1 Jun 2025 09:52:11 +0200

On Sun, Jun 1, 2025 at 7:38 AM Eli Zaretskii <[email-masked]> wrote:

> > From: Marco Antoniotti <[email-masked]>
> > Date: Sat, 31 May 2025 23:58:26 +0200
> > Cc: Stefan Monnier <[email-masked]>, [email-masked]
> >
> >    (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
-- 
Marco Antoniotti
Somewhere over the Rainbow