master 6b8bb47 2/2: Fill some auto-generated docstrings

[Stefan Kangas]

branch: master
commit 6b8bb47ac085700740feaad24a591a8bbec3a71c
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    Fill some auto-generated docstrings
    
    * lisp/emacs-lisp/easy-mmode.el (define-minor-mode)
    (define-globalized-minor-mode): Fill auto-generated documentation
    strings.  (Bug#44858)
    * lisp/subr.el (internal--fill-string-single-line)
    (internal--format-docstring-line): New functions.
---
 lisp/emacs-lisp/derived.el    | 42 +++++++++++++++++++++++-------------------
 lisp/emacs-lisp/easy-mmode.el | 39 ++++++++++++++++++++-------------------
 lisp/subr.el                  | 18 ++++++++++++++++++
 3 files changed, 61 insertions(+), 38 deletions(-)

diff --git a/lisp/emacs-lisp/derived.el b/lisp/emacs-lisp/derived.el
index 6a11f1c..dee5072 100644
--- a/lisp/emacs-lisp/derived.el
+++ b/lisp/emacs-lisp/derived.el
@@ -306,11 +306,13 @@ No problems result if this variable is not bound.
       ;; 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--format-docstring-line
+                  "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 @@ which more-or-less shadow%s %s's corresponding table%s."
     (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--format-docstring-line
+                     "%s%s%s"
+                     (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/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 261f250..1344c33 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -278,8 +278,10 @@ For example, you could write
          ((not globalp)
           `(progn
              :autoload-end
-             (defvar ,mode ,init-value ,(format "Non-nil if %s is enabled.
-Use the command `%s' to change this variable." pretty-name mode))
+             (defvar ,mode ,init-value
+               ,(concat (format "Non-nil if %s is enabled.\n" pretty-name)
+                        (internal--format-docstring-line
+                         "Use the command `%s' to change this variable." 
mode)))
              (make-variable-buffer-local ',mode)))
          (t
          (let ((base-doc-string
@@ -455,24 +457,23 @@ on if the hook has explicitly disabled it.
          (make-variable-buffer-local ',MODE-major-mode))
        ;; The actual global minor-mode
        (define-minor-mode ,global-mode
-        ;; Very short lines to avoid too long lines in the generated
-        ;; doc string.
-        ,(format "Toggle %s in all buffers.
-With prefix ARG, enable %s if ARG is positive;
-otherwise, disable it.  If called from Lisp, enable the mode if
-ARG is omitted or nil.
-
-%s is enabled in all buffers where
-`%s' would do it.
-
-See `%s' for more information on
-%s.%s"
-                 pretty-name pretty-global-name
-                 pretty-name turn-on mode pretty-name
+         ,(concat (format "Toggle %s in all buffers.\n" pretty-name)
+                  (internal--format-docstring-line
+                   "With prefix ARG, enable %s if ARG is positive; otherwise, \
+disable it.  If called from Lisp, enable the mode if ARG is omitted or 
nil.\n\n"
+                   pretty-global-name)
+                  (internal--format-docstring-line
+                   "%s is enabled in all buffers where `%s' would do it.\n\n"
+                   pretty-name turn-on)
+                  (internal--format-docstring-line
+                   "See `%s' for more information on %s."
+                   mode pretty-name)
                   (if predicate
-                      (format "\n\n`%s' is used to control which modes
-this minor mode is used in."
-                              MODE-predicate)
+                      (concat
+                       "\n\n"
+                       (internal--format-docstring-line
+                        "`%s' is used to control which modes this minor mode 
is used in."
+                        MODE-predicate))
                     ""))
          :global t ,@group ,@(nreverse extra-keywords)
 
diff --git a/lisp/subr.el b/lisp/subr.el
index 725722c..384dbb25 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -5973,4 +5973,22 @@ seconds."
      ;; Continue running.
      nil)))
 
+(defun internal--fill-string-single-line (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 (< (string-width 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-single-line lst)))))
+
+(defun internal--format-docstring-line (string &rest objects)
+  "Format a documentation string out of STRING and OBJECTS.
+This is intended for internal use only."
+  (internal--fill-string-single-line (apply #'format string objects)))
+
 ;;; subr.el ends here