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

Previous Next

Full log

Message #23 received at 78543 <at> debbugs.gnu.org (full text, mbox):

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

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

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

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

Previous Next

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