emacs-28 6c01a21: Clarify the purpose of internal--format-docstring-line

[Stefan Kangas]

branch: emacs-28
commit 6c01a213656cc1d38c9ac0b127583910a9296365
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    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 <monnier@iro.umontreal.ca>.
---
 lisp/emacs-lisp/cl-macs.el |  8 ++++++++
 lisp/subr.el               |  4 +++-
 test/lisp/subr-tests.el    | 15 +++++++--------
 3 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 527720c..1852471 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 1d298080..a8fb52c 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 ed9a3d0..0da1ae9 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))