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: Eli Zaretskii <eliz <at> gnu.org>
To: Bohong Huang <bohonghuang <at> qq.com>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 77047 <at> debbugs.gnu.org
Subject: bug#77047: 30.1; `cl-defgeneric`'s docstrings in `:documentation` are not recognized by `checkdoc`
Date: Sun, 16 Mar 2025 14:25:01 +0200

> Date: Sun, 16 Mar 2025 15:06:08 +0800
> From:  Bohong Huang via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> Hello Emacs maintainers,
> 
> While using `cl-defgeneric` from `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?
> 
> 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. 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.
> 
> What are your thoughts on this? Thank you in advance for your time and
> consideration.

Adding Stefan to the discussion.

Previous Next

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