[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#65790: 29.1; "docstring wider than 80 characters" when there is no d
From: |
Stefan Kangas |
Subject: |
bug#65790: 29.1; "docstring wider than 80 characters" when there is no docstring |
Date: |
Sun, 10 Sep 2023 02:55:59 -0700 |
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