> From: Marco Antoniotti <marcoxa@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.