bug#44858: [PATCH] Make byte-compiler warn about wide docstrings

[Stefan Kangas <stefan@marxist.se>]

[-- Attachment #1: Type: text/plain, Size: 284 bytes --]

Stefan Kangas <stefan@marxist.se> writes:

> 2. Avoid wide docstrings in define-minor-mode.

And here's a patch also for define-derived-mode.

It seems like we still need to fix cl-defun, cl-defstruct,
define-globalized-minor-mode and perhaps a few others.
So I'll work on that next.

[-- Attachment #2: 0004-Fill-docstrings-in-define-derived-mode.patch --]
[-- Type: text/x-diff, Size: 4063 bytes --]

From 50f2a3cce5de966599952fdd1e6ea05913a950b1 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Thu, 10 Dec 2020 22:36:18 +0100
Subject: [PATCH] Fill docstrings in define-derived-mode

* lisp/subr.el (internal--fill-string): New function.
* lisp/emacs-lisp/derived.el (derived-mode-make-docstring): Fill
docstrings.
---
 lisp/emacs-lisp/derived.el | 42 +++++++++++++++++++++-----------------
 lisp/subr.el               | 13 ++++++++++++
 2 files changed, 36 insertions(+), 19 deletions(-)

diff --git a/lisp/emacs-lisp/derived.el b/lisp/emacs-lisp/derived.el
index 6a11f1c394..00a6c12b10 100644
--- a/lisp/emacs-lisp/derived.el
+++ b/lisp/emacs-lisp/derived.el
@@ -306,11 +306,13 @@ derived-mode-make-docstring
       ;; Use a default docstring.
       (setq docstring
 	    (if (null parent)
-		;; FIXME filling.
-		(format "Major-mode.\nUses keymap `%s'%s%s." map
-			(if abbrev (format "%s abbrev table `%s'"
-					   (if syntax "," " and") abbrev) "")
-			(if syntax (format " and syntax-table `%s'" syntax) ""))
+                (concat
+                 "Major-mode.\n"
+                 (internal--fill-string
+                  (format "Uses keymap `%s'%s%s." map
+                          (if abbrev (format "%s abbrev table `%s'"
+                                             (if syntax "," " and") abbrev) "")
+                          (if syntax (format " and syntax-table `%s'" syntax) ""))))
 	      (format "Major mode derived from `%s' by `define-derived-mode'.
 It inherits all of the parent's attributes, but has its own keymap%s:
 
@@ -336,20 +338,22 @@ derived-mode-make-docstring
     (unless (string-match (regexp-quote (symbol-name hook)) docstring)
       ;; Make sure the docstring mentions the mode's hook.
       (setq docstring
-	    (concat docstring
-		    (if (null parent)
-			"\n\nThis mode "
-		      (concat
-		       "\n\nIn addition to any hooks its parent mode "
-		       (if (string-match (format "[`‘]%s['’]"
-                                                 (regexp-quote
-						  (symbol-name parent)))
-					 docstring)
-                           nil
-			 (format "`%s' " parent))
-		       "might have run,\nthis mode "))
-		    (format "runs the hook `%s'" hook)
-		    ", as the final or penultimate step\nduring initialization.")))
+            (concat docstring "\n\n"
+                    (internal--fill-string
+                     (concat
+                      (if (null parent)
+                          "This mode "
+                        (concat
+                         "In addition to any hooks its parent mode "
+                         (if (string-match (format "[`‘]%s['’]"
+                                                   (regexp-quote
+                                                    (symbol-name parent)))
+                                           docstring)
+                             nil
+                           (format "`%s' " parent))
+                         "might have run, this mode "))
+                      (format "runs the hook `%s'" hook)
+                      ", as the final or penultimate step during initialization.")))))
 
     (unless (string-match "\\\\[{[]" docstring)
       ;; And don't forget to put the mode's keymap.
diff --git a/lisp/subr.el b/lisp/subr.el
index c28807f694..4d10b70db7 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -5927,4 +5927,17 @@ run-hook-query-error-with-timeout
      ;; Continue running.
      nil)))
 
+(defun internal--fill-string (str)
+  "Fill string STR to `fill-column'.
+This is intended for very simple filling while bootstrapping
+Emacs itself, and does not support all the customization options
+of fill.el (for example `fill-region')."
+  (if (< (length str) fill-column)
+      str
+    (let ((fst (substring str 0 fill-column))
+          (lst (substring str fill-column)))
+      (if (string-match ".*\\( \\(.+\\)\\)$" fst)
+          (setq fst (replace-match "\n\\2" nil nil fst 1)))
+      (concat fst (internal--fill-string lst)))))
+
 ;;; subr.el ends here
-- 
2.29.2