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

Previous Next

Full log

View this message in rfc822 format

From: Marco Antoniotti <marcoxa <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78543-done <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs.
Date: Sat, 7 Jun 2025 11:54:04 +0200

[Message part 1 (text/plain, inline)]

Hi

you mean you are willing to go against the collective will of the CL
Community at large? 🥹😏😁😑

On Sat, Jun 7, 2025 at 11:18 AM Eli Zaretskii <eliz <at> gnu.org> wrote:

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


-- 
Marco Antoniotti
Somewhere over the Rainbow

[Message part 2 (text/html, inline)]

Previous Next

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