GNU bug report logs - #77047
30.1; `cl-defgeneric`'s docstrings in `:documentation` are not recognized by `checkdoc`

Previous Next

Full log

View this message in rfc822 format

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77047 <at> debbugs.gnu.org, Bohong Huang <bohonghuang <at> qq.com>
Subject: bug#77047: 30.1; `cl-defgeneric`'s docstrings in `:documentation` are not recognized by `checkdoc`
Date: Sun, 16 Mar 2025 22:19:23 -0400

>> While using `cl-defgeneric` from `cl-lib`,

[ Nitpick: `cl-defgeneric` is not part of `cl-lib`.  ]

>> I noticed that even when I write the docstring in `(:documentation
>> "...")`, checkdoc still complains that it is undefined. However, the
>> documentation for `cl-defgeneric` does state two supported ways to
>> define docstrings.
>> Could this be a checkdoc-related bug?

Sounds like it, yes.  At least both forms set the
`function-documentation` property in my test, so they both work
in practice.

>> I am aware that placing the docstring directly in the body (as the sole
>> form) silences the error. However, in fact, ANSI CL does not permit
>> this, and treating a lone string in the `cl-defgeneric` body as a
>> docstring can be ambiguous. Considering that since Emacs 30, `defun` no
>> longer treats a lone string in the body as a docstring, for consistency,
>> `cl-defgeneric` should follow suit.

Indeed our `cl-defgeneric` supports a `&rest body` (which, when non-nil,
defines a default method) contrary to CLOS's, so there's the question
whether that string is part of the default method or part of the overall
generic function.

The interesting corner case comes with things like;

    (cl-defgeneric my-gen3 (a) (:documentation "hello") "there")

where "there" is not taken as a docstring, contrary to:

    (cl-defgeneric my-gen3 (a) "there")

>> However, this would imply providing a default method that returns
>> a string.  My suggestion is to discourage docstrings in the body
>> (aligning with `defun`) and encourage using `(:documentation)` when
>> declaring a generic function without a default method, and allow the
>> current syntax (docstring in the body) only when defining both the
>> generic function and its default method.

I find the (:documentation ...) form somewhat inconvenient (for purely
aesthetic reasons), so I'd rather not have to use it too often.
That preference of mine is reflected in the behavior I implemented.

But if the use of a "plain docstring" without a default method is
sufficiently rare, I wouldn't be opposed to deprecating its use.


        Stefan

Previous Next

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