Subject: Re: bug#65790: 29.1; "docstring wider than 80 characters" when there is no docstring

From: Damien Cassou <[email-masked]>
Date: Sun, 10 Sep 2023 08:47:42 +0200

Stefan Kangas <[email-masked]> writes:
> That's basically the solution, yes, but we probably want to wrap the
> lines only when it's necessary.  See `internal--fill-string-single-line'
> and where it is used for inspiration.

What do you think about attached patch? The patch replaces one usage of
`format' with `internal--format-docstring-line' and also slightly change
2 docstring texts.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill
>From 093c76caa8ac551868565d0e690b9979593cf94d Mon Sep 17 00:00:00 2001
From: Damien Cassou <[email-masked]>
Date: Sun, 10 Sep 2023 08:40:52 +0200
Subject: [PATCH] Shorten docstrings generated in cl-macs.el

* lisp/emacs-lisp/cl-macs.el (cl-defsubst): Reduce likelihood of
"docstring wider than 80 characters" errors in generated code.
---
 lisp/emacs-lisp/cl-macs.el | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index c8e2610c8b0..0f142b87e07 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2931,7 +2931,15 @@ cl-defsubst
              ,(if (memq '&key args)
                   `(&whole cl-whole &cl-quote ,@args)
                 (cons '&cl-quote args))
-             ,(format "compiler-macro for inlining `%s'." name)
+             ;; 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 "compiler-macro for `%s'." name)
              (cl--defsubst-expand
               ',argns '(cl-block ,name ,@(cdr (macroexp-parse-body body)))
               nil
@@ -3190,7 +3198,10 @@ cl-defstruct
                          ;; 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)
+                          "Access slot \"%s\" of CL-X." slot)
+                         "\n"
+                         (internal--format-docstring-line
+                          "Struct CL-X is a `%s'." name)
                          (if doc (concat "\n" doc) ""))
                        (declare (side-effect-free t))
                        ,access-body)
-- 
2.41.0