From 6c01a213656cc1d38c9ac0b127583910a9296365 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 2 Oct 2021 21:56:22 +0200 Subject: Clarify the purpose of internal--format-docstring-line * 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 . --- lisp/emacs-lisp/cl-macs.el | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'lisp/emacs-lisp') diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el index 527720c6e8d..1852471bcbb 100644 --- a/lisp/emacs-lisp/cl-macs.el +++ b/lisp/emacs-lisp/cl-macs.el @@ -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) "")) -- cgit v1.2.3