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

Previous Next

Full log

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

From: Marco Antoniotti <marcoxa <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78543 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#78543: 29.2; checkdoc misses some CL (cl-lib) constructs.
Date: Sat, 31 May 2025 23:58:26 +0200

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

Hi...

On Sat, May 31, 2025 at 1:07 PM Eli Zaretskii <eliz <at> gnu.org> wrote:

> > From: Marco Antoniotti <marcoxa <at> gmail.com>
> > Date: Wed, 21 May 2025 22:38:48 +0200
> >
> > The problem is with `checkdoc` not correctly handling some docstring
> > in `cl-lib` style declarations.
> >
> > I have a function like
> >
> > ```
> > (cl-defun funky-keys (&key ((:this that) 42) &aux (the-beast 666))
> >     "Do something with THAT (passed via :THIS)"
> >     ...
> >     )
> > ```
> >
> > checkdoc insists on flagging :THIS and THE-BEAST as missing from the
> docstring.
> >
> > Another one is the following.
> >
> > ```
> > (cl-defgeneric gf (a s d f)
> >     (:documentation "Munge A, S, D, and F."))
> > ```
> >
> > checkdoc does not recognize the :documentation option (which is valid
> according to cl-lib).
> >
> > This problem is still visible in 30.1
>
> Sigh.  This is notoriously under-documented in the cl.info manual.
> After reading and re-reading the node "Argument Lists" there, I
> believe that we expect :this to be referenced as "THIS" (without the
> leading colon) in the doc string, since argument references in doc
> strings should be words, not symbols, and ':' is not a
> word-constituent character.  Also, I believe that THE-BEAST should
> indeed be mentioned in the doc string.  This:
>
>   (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).

THE-BEAST should NOT be flagged as it is definitively not part of the
function signature.  &aux variables should be ignored for doc strings.

Any update on the cl-defgeneric :documentation slot?

My 2 cents:  Yes Emacs Lisp should support CL idioms.  CL got many things
right in the base language (yes Virginia! I know about pathnames :) ).

All the best

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