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. > 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