From 97beb0b1f93481e9eba6e3f70d079b2b3d14ade8 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 10 Dec 2020 22:36:18 +0100 Subject: [PATCH 2/2] 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 6a11f1c394..dee507269b 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--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 @@ 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--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 261f2508af..1344c3391b 100644 --- a/lisp/emacs-lisp/easy-mmode.el +++ b/lisp/emacs-lisp/easy-mmode.el @@ -278,8 +278,10 @@ define-minor-mode ((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 @@ define-globalized-minor-mode (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 1b2d778454..0a46221a7f 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -5952,4 +5952,22 @@ run-hook-query-error-with-timeout ;; 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 -- 2.29.2