From: Mattias Engdegård <mattiase@acm.org>
Date: Fri, 23 Feb 2024 12:57:04 +0000 (+0100)
Subject: Warn about docstrings with control characters
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7f0af2513d68d85b4b6422d139a122696b99994c;p=emacs.git

Warn about docstrings with control characters

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.

(cherry picked from commit 90d3b3408e404aba383302c3147d3ca614619986)
---

diff --git a/etc/NEWS b/etc/NEWS
index cabd2778bae..62be6461796 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2070,6 +2070,20 @@ name 'ignored-return-value'.
 The warning will only be issued for calls to functions declared
 'important-return-value' or 'side-effect-free' (but not 'error-free').
 
+---
+*** Warn about docstrings that contain control characters.
+The compiler now warns about docstrings with control characters other
+than newline and tab.  This is often a result of improper escaping.
+Example:
+
+    (defun my-fun ()
+      "Uses c:\remote\dir\files and the key \C-x."
+      ...)
+
+where the doc string contains four control characters CR, DEL, FF and ^X.
+
+The warning name is 'docstrings-control-chars'.
+
 ---
 *** The warning about wide docstrings can now be disabled separately.
 Its warning name is 'docstrings-wide'.
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 5d2aa3355be..c3355eedd75 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -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)