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

Clarify the purpose of internal--format-docstring-line

Browse source 
* test/lisp/subr-tests.el (subr-test-internal--format-docstring-line):
* lisp/subr.el (internal--format-docstring-line): Make it more clear
that this function is not intended for the first line of a docstring.
* lisp/emacs-lisp/cl-macs.el (cl-defstruct): Add comment explaining
why we use 'internal--format-docstring-line'.
Problem pointed out by Stefan Monnier <monnier@iro.umontreal.ca>.
This commit is contained in:
Stefan Kangas 2021-10-02 21:56:22 +02:00
parent 55dadbc57e
commit 6c01a21365
3 changed files with 18 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
lisp/emacs-lisp/cl-macs.el
View file

@ -3087,6 +3087,14 @@ To see the documentation for a defined struct type, use
;; and pred-check, so changing it is not straightforward.
(push `(,defsym ,accessor (cl-x)
,(concat
;; NB. This will produce incorrect results
;; in some cases, as our coding conventions
;; says that the first line must be a full
;; sentence. However, if we don't word wrap
;; we will have byte-compiler warnings about
;; overly long docstrings. So we can't have
;; a perfect result here, and choose to avoid
;; the byte-compiler warnings.
(internal--format-docstring-line
"Access slot \"%s\" of `%s' struct CL-X." slot name)
(if doc (concat "\n" doc) ""))

4
lisp/subr.el
View file

@ -6437,7 +6437,9 @@ of fill.el (for example `fill-region')."
(defun internal--format-docstring-line (string &rest objects)
"Format a single line from a documentation string out of STRING and OBJECTS.
Signal an error if STRING contains a newline.
This is intended for internal use only."
This is intended for internal use only. Avoid using this for the
first line of a docstring; the first line should be a complete
sentence (see Info node `(elisp) Documentation Tips')."
(when (string-match "\n" string)
(error "Unable to fill string containing newline: %S" string))
(internal--fill-string-single-line (apply #'format string objects)))

15
test/lisp/subr-tests.el
View file

@ -769,15 +769,14 @@ See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=19350."
(ert-deftest subr-test-internal--format-docstring-line ()
(should
(string= (let ((fill-column 60))
(string= (let ((fill-column 70))
(internal--format-docstring-line
"Emacs is the advanced, extensible, customizable, \
self-documenting editor. This manual describes how to edit with Emacs and \
some of the ways to customize it; it corresponds to GNU Emacs version 28.1."))
"Emacs is the advanced, extensible, customizable,
self-documenting editor. This manual describes how to edit
with Emacs and some of the ways to customize it; it
corresponds to GNU Emacs version 28.1.")))
"In addition to any hooks its parent mode might have run, this \
mode runs the hook ‘foo-bar-baz-very-long-name-indeed-mode-hook’, as the final \
or penultimate step during initialization."))
"In addition to any hooks its parent mode might have run, this mode
runs the hook ‘foo-bar-baz-very-long-name-indeed-mode-hook’, as the
final or penultimate step during initialization.")))
(ert-deftest test-ensure-list ()
(should (equal (ensure-list nil) nil))