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

Warn about docstrings with control characters

Browse source 
It is easy to include control chars in doc strings by mistake, and the
result is often an unreadable mess.

* lisp/emacs-lisp/bytecomp.el (byte-compile-warning-types)
(byte-compile-warnings, byte-compile--docstring-style-warn):
Add `docstrings-control-chars` warning.
* etc/NEWS: Announce.
This commit is contained in:
Mattias Engdegård 2024-02-23 13:57:04 +01:00
parent a8f167547b
commit 90d3b3408e
2 changed files with 35 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

21
lisp/emacs-lisp/bytecomp.el
View file

@ -285,6 +285,7 @@ The information is logged to `byte-compile-log-buffer'."
(defconst byte-compile-warning-types
'( callargs constants
docstrings docstrings-non-ascii-quotes docstrings-wide
docstrings-control-chars
empty-body free-vars ignored-return-value interactive-only
lexical lexical-dynamic make-local
mapcar ; obsolete
@ -307,6 +308,8 @@ Elements of the list may be:
docstrings that are too wide, containing lines longer than both
`byte-compile-docstring-max-column' and `fill-column' characters.
Only enabled when `docstrings' also is.
docstrings-control-chars
docstrings that contain control characters other than NL and TAB
empty-body body argument to a special form or macro is empty.
free-vars references to variables not in the current lexical scope.
ignored-return-value
@ -1769,6 +1772,24 @@ It is too wide if it has any lines longer than the largest of
(byte-compile-warn-x
name
"%sdocstring wider than %s characters" (funcall prefix) col)))
(when (byte-compile-warning-enabled-p 'docstrings-control-chars)
(let ((start 0)
(len (length docs)))
(while (and (< start len)
(string-match (rx (intersection (in (0 . 31) 127)
(not (in "\n\t"))))
docs start))
(let* ((ofs (match-beginning 0))
(c (aref docs ofs)))
;; FIXME: it should be possible to use the exact source position
;; of the control char in most cases, and it would be helpful
(byte-compile-warn-x
name
"%sdocstring contains control char #x%02x (position %d)"
(funcall prefix) c ofs)
(setq start (1+ ofs))))))
;; There's a "naked" ' character before a symbol/list, so it
;; should probably be quoted with \=.
(when (string-match-p (rx (| (in " \t") bol)