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) "")) diff --git a/lisp/subr.el b/lisp/subr.el index 1d2980802e0..a8fb52c9098 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -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))) diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el index ed9a3d01498..0da1ae96873 100644 --- a/test/lisp/subr-tests.el +++ b/test/lisp/subr-tests.el @@ -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))