procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Shorten docstrings generated by cl-defstruct

Browse source 
* lisp/emacs-lisp/cl-macs.el (cl-defstruct): Split the first line of
generated docstrings if either the struct name or a field name is very
long.  This reduces the likelihood of "docstring wider than 80
characters" errors.  (Bug#65790)
This commit is contained in:
Damien Cassou 2023-09-12 08:28:37 +02:00 • committed by Stefan Kangas
parent f045750fa5
commit 1f7113e689
2 changed files with 48 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
lisp/emacs-lisp/cl-macs.el
View file

@ -3187,18 +3187,27 @@ To see the documentation for a defined struct type, use
;; The arg "cl-x" is referenced by name in e.g. pred-form
;; 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) ""))
,(let ((long-docstring
(format "Access slot \"%s\" of `%s' struct CL-X." slot name)))
(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.
(if (>= (length long-docstring) byte-compile-docstring-max-column)
(concat
(internal--format-docstring-line
"Access slot \"%s\" of CL-X." slot)
"\n"
(internal--format-docstring-line
"Struct CL-X is a `%s'." name))
(internal--format-docstring-line long-docstring))
(if doc (concat "\n" doc) "")))
(declare (side-effect-free t))
,access-body)
forms)
@ -3274,7 +3283,16 @@ To see the documentation for a defined struct type, use
(push `(,cldefsym ,cname
(&cl-defs (nil ,@descs) ,@args)
,(if (stringp doc) doc
(format "Constructor for objects of type `%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
"Constructor for objects of type `%s'." name))
,@(if (cl--safe-expr-p `(progn ,@(mapcar #'cl-second descs)))
'((declare (side-effect-free t))))
(,con-fun ,@make))

17
test/lisp/emacs-lisp/bytecomp-tests.el
View file

@ -983,6 +983,23 @@ byte-compiled. Run with dynamic binding."
`(cl-defsubst long-name-with-more-than-80-characters-yes-this-is-a-very-long-name-but-why-not!! ()
"Do something.")))
(ert-deftest bytecomp-warn-wide-docstring/cl-defstruct ()
(bytecomp--without-warning-test
`(cl-defstruct short-name
field))
(bytecomp--without-warning-test
`(cl-defstruct short-name
long-name-with-less-80-characters-but-still-quite-a-bit))
(bytecomp--without-warning-test
`(cl-defstruct long-name-with-less-80-characters-but-still-quite-a-bit
field))
(bytecomp--with-warning-test "wider than.*characters"
`(cl-defstruct short-name
long-name-with-more-than-80-characters-yes-this-is-a-very-long-name-but-why-not!!))
(bytecomp--with-warning-test "wider than.*characters"
`(cl-defstruct long-name-with-more-than-80-characters-yes-this-is-a-very-long-name-but-why-not!!
field)))
(ert-deftest bytecomp-warn-quoted-condition ()
(bytecomp--with-warning-test
"Warning: `condition-case' condition should not be quoted: 'arith-error"