Subject: bug#56968: Incorrect definition prefix "my-" assigned to battery.el in ldefs-boot.el

From: Lars Ingebrigtsen <[email-masked]>
Date: Thu, 04 Aug 2022 11:01:16 +0200

Stefan Kangas <[email-masked]> writes:

> Severity: minor
>
> I see in ldefs-boot.el:
>
>     (register-definition-prefixes "battery" '("battery-" "my-"))
>
> However, in battery.el, the "my-" prefix only ever shows up inside a
> docstring.  That seems like a bug.
>
> AFAICT, this doesn't happen in emacs-28, so this might be a regression.

The (defun my- in battery.el is new in Emacs 29, so it's not a
regression exactly -- it's why we're doing \( in all doc strings that
have lines that start with (def.

I briefly wondered whether we could usefully warn about this with
something like the below, but I don't think so, since by the time we're
called where, we've already read the \( into (, so there's too many
false positives.

So I've just fixed up the existing errors here instead.

diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 7d2971502d..d8255b2584 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -294,7 +294,8 @@ byte-compile-warning-types
   '(redefine callargs free-vars unresolved
              obsolete noruntime interactive-only
              make-local mapcar constants suspicious lexical lexical-dynamic
-             docstrings docstrings-non-ascii-quotes not-unused)
+             docstrings docstrings-non-ascii-quotes not-unused
+             docstrings-defthings)
   "The list of warning types used when `byte-compile-warnings' is t.")
 (defcustom byte-compile-warnings t
   "List of warnings that the byte-compiler should issue (t for almost all).
@@ -338,7 +339,8 @@ byte-compile-warnings
                                 byte-compile-warning-types))))
 
 (defconst byte-compile--emacs-build-warning-types
-  '(docstrings-non-ascii-quotes)
+  '(docstrings-non-ascii-quotes
+    docstrings-defthings)
   "List of warning types that are only enabled during Emacs builds.
 This is typically either warning types that are being phased in
 (but shouldn't be enabled for packages yet), or that are only relevant
@@ -1770,6 +1772,13 @@ byte-compile-docstring-style-warn
           (when (string-match-p "\\( \"\\|[ \t]\\|^\\)[‘’]" docs)
             (byte-compile-warn-x
              name "%s%sdocstring has wrong usage of \"fancy\" single quotation marks"
+             kind name)))
+        ;; There's a "(def" in the first column.  This will typically
+        ;; lead to wrong `register-definition-prefixes'.
+        (when (byte-compile-warning-enabled-p 'docstrings-defthings)
+          (when (string-match-p "^(def" docs)
+            (byte-compile-warn-x
+             name "%s%sdocstring has a \"(def\" form in the first column"
              kind name))))))
   form)