procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fill some auto-generated docstrings

Browse source 
* 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.
This commit is contained in:
Stefan Kangas 2020-12-10 22:36:18 +01:00
parent 0ebea8ffbf
commit 6b8bb47ac0
3 changed files with 61 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

42
lisp/emacs-lisp/derived.el
View file

@ -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.

39
lisp/emacs-lisp/easy-mmode.el
View file

@ -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)