procyberian/emacs
2
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
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) ""))