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

[Stefan Kangas <stefankangas@gmail.com>]

Damien Cassou <damien@cassou.me> writes:

> 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.

Thanks, some comments below.

I think this also could use some tests, see bytecomp-tests.el:964 and
onwards.

> From 093c76caa8ac551868565d0e690b9979593cf94d Mon Sep 17 00:00:00 2001
> From: Damien Cassou <damien@cassou.me>
> 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.

Please remember to include the bug number when it is known.

> ---
>  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)

Why drop the word "inlining"?

(This comment might need reflowing.)

>               (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)

Could we keep the old format when possible, and use the new one only
when needed?

>                           (if doc (concat "\n" doc) ""))
>                         (declare (side-effect-free t))
>                         ,access-body)
> --
> 2.41.0