GNU bug report logs - #69226
29.2.50; elisp-flymake-checkdoc complains about mentioning defclass

Previous Next

To reply to this bug, email your comments to 69226 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

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

From: Spencer Baugh <sbaugh <at> janestreet.com>
To: bug-gnu-emacs <at> gnu.org
Cc: Eric Ludlam <zappo <at> gnu.org>, Stefan Kangas <stefankangas <at> gmail.com>
Subject: 29.2.50; elisp-flymake-checkdoc complains about mentioning defclass
Date: Fri, 16 Feb 2024 10:28:00 -0500

1. emacs -Q
2. Create file containing:
(defclass my-class () ())
(defvar my-value nil
 "A useful value.

Should be of type `my-class' or nil")
(defun my-func ()
"Does something.

The return value is of type `my-class'.")
3. M-x flymake-mode
4. Observe warnings about:
Disambiguate my-class by preceding w/ function,command,variable,option or symbol.

The issue is that `my-class' is both a variable and a function.

I could rewrite the docstrings to say
"Should be produced by the function `my-class', or nil."
"The return value is produced by calling the function `my-class'."

but that's awkward wording.

It would be nice if checkdoc would recognize "type" before a quoted
symbol as removing the ambiguity.

Also, it might be nice if the docstring parser recognized "type" as
indicating that it should link to the function definition, not the
variable definition, since the variable definition is deprecated anyway.


In GNU Emacs 29.2.50 (build 2, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.15.12, Xaw scroll bars) of 2024-01-24 built on
 igm-qws-u22796a
Repository revision: 09ba5f12dd85cdff266b9bbb3f8510abdfd67a62
Repository branch: emacs-29
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Rocky Linux 8.9 (Green Obsidian)

Configured using:
 'configure 'CFLAGS=-O0 -g3' --with-gif=ifavailable
 --with-x-toolkit=lucid'

Configured features:
CAIRO DBUS FREETYPE GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LIBSELINUX LIBSYSTEMD LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG RSVG
SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM
XINPUT2 XPM LUCID ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Info

Memory information:
((conses 16 2072917 190283)
 (symbols 48 66336 0)
 (strings 32 350168 31566)
 (string-bytes 1 15047792)
 (vectors 16 134982)
 (vector-slots 8 2606522 206024)
 (floats 8 946 592)
 (intervals 56 118464 832)
 (buffers 976 333))

Previous Next

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