procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

checkdoc: Delete redundant check for wide docstrings

Browse source 
With Emacs 28.1, wide docstrings are now flagged by the byte-compiler.
The logic in the byte-compiler for catching these issues is complex
and continuously evolving, particularly to avoid incorrectly flagging
`substitute-command-keys` substitutions.  Unfortunately, the checkdoc
implementation incorrectly flags correct docstrings as overly wide.

Rather than duplicating the byte-compiler logic in checkdoc, which
would introduce unnecessary maintenance overhead, we acknowledge that
this check is now redundant and remove it.  Users utilizing the
byte-compiler, whether manually or through `flymake`, will continue to
be warned about this issue.

* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
Remove check for overly wide docstrings; duplicates byte-compiler
logic.
This commit is contained in:
Stefan Kangas 2025-03-23 17:22:51 +01:00
parent 7d14e35498
commit 408ad273ee
2 changed files with 5 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
etc/NEWS
View file

@ -1024,6 +1024,11 @@ those versions can't install packages where that line is missing.
This change affects both 'M-x checkdoc' and the corresponding flymake
backend.
---
*** Checkdoc no longer warns about wide docstrings.
The Checkdoc warning for wide docstrings duplicates the byte-compiler
warning added in Emacs 28.1. This redundancy is now removed.
---
*** New user option 'checkdoc-arguments-missing-flag'.
Set this to nil to disable warnings for function arguments that are not

29
lisp/emacs-lisp/checkdoc.el
View file

@ -1694,35 +1694,6 @@ function,command,variable,option or symbol." ms1))))))
(if ret
(checkdoc-create-error ret mb me)
nil)))
;; * Format the documentation string so that it fits in an
;; Emacs window on an 80-column screen. It is a good idea
;; for most lines to be no wider than 60 characters. The
;; first line can be wider if necessary to fit the
;; information that ought to be there.
(save-excursion
(let* ((start (point))
(eol nil)
;; Respect this file local variable.
(max-column (max 80 byte-compile-docstring-max-column))
;; Allow the first line to be three characters longer, to
;; fit the leading ` "' while still having a docstring
;; shorter than e.g. 80 characters.
(first t)
(get-max-column (lambda () (+ max-column (if first 3 0)))))
(while (and (< (point) e)
(or (progn (end-of-line) (setq eol (point))
(< (current-column) (funcall get-max-column)))
(progn (beginning-of-line)
(re-search-forward "\\\\\\\\[[<{]"
eol t))
(checkdoc-in-sample-code-p start e)))
(setq first nil)
(forward-line 1))
(end-of-line)
(if (and (< (point) e) (> (current-column) (funcall get-max-column)))
(checkdoc-create-error
(format "Some lines are over %d columns wide" max-column)
s (save-excursion (goto-char s) (line-end-position))))))
;; Here we deviate to tests based on a variable or function.
;; We must do this before checking for symbols in quotes because there
;; is a chance that just such a symbol might really be an argument.