[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 6b8bb47 2/2: Fill some auto-generated docstrings
From: |
Stefan Kangas |
Subject: |
master 6b8bb47 2/2: Fill some auto-generated docstrings |
Date: |
Mon, 28 Dec 2020 00:14:13 -0500 (EST) |
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