[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/bug-44858 35c459f 6/6: Warn about overly long docstring in lambd
From: |
Stefan Kangas |
Subject: |
scratch/bug-44858 35c459f 6/6: Warn about overly long docstring in lambda |
Date: |
Fri, 24 Sep 2021 13:19:53 -0400 (EDT) |
branch: scratch/bug-44858
commit 35c459fd88cbf8dbd71fa81437ff78c1ee84aaa4
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>
Warn about overly long docstring in lambda
* lisp/emacs-lisp/bytecomp.el
(byte-compile-docstring-length-warn): Warn about overly long
docstring in lambda. (Bug#44858)
(byte-compile--wide-docstring-p): Improve comment.
* test/lisp/emacs-lisp/bytecomp-tests.el
("warn-wide-docstring-defun.el"): Update to test for the above new
warning.
---
lisp/emacs-lisp/bytecomp.el | 22 ++++++++--------------
test/lisp/emacs-lisp/bytecomp-tests.el | 3 +--
2 files changed, 9 insertions(+), 16 deletions(-)
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index a3a3701..091fba4 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -1666,7 +1666,10 @@ URLs."
(seq "(" (* (not ")")) ")")))
")")))
""
- ;; Heuristic: assume these substitutions are of some length N.
+ ;; Heuristic: We assume that these `subsititute-command-keys'
+ ;; substitutions are of some length N (more precisely, N=1). We
+ ;; can't reliably do these replacements, since the value of the
+ ;; keymaps in general can't be known at compile time.
(replace-regexp-in-string
(rx "\\" (or (seq "[" (* (not "]")) "]")))
(make-string byte-compile--wide-docstring-substitution-len ?x)
@@ -1686,13 +1689,6 @@ value, it will override this variable."
"Warn if documentation string of FORM is too wide.
It is too wide if it has any lines longer than the largest of
`fill-column' and `byte-compile-docstring-max-column'."
- ;; This has some limitations that it would be nice to fix:
- ;; 1. We don't try to handle defuns. It is somewhat tricky to get
- ;; it right since `defun' is a macro. Also, some macros
- ;; themselves produce defuns (e.g. `define-derived-mode').
- ;; 2. We assume that any `subsititute-command-keys' command replacement has a
- ;; given length. We can't reliably do these replacements, since the value
- ;; of the keymaps in general can't be known at compile time.
(when (byte-compile-warning-enabled-p 'docstrings)
(let ((col (max byte-compile-docstring-max-column fill-column))
kind name docs)
@@ -1703,12 +1699,10 @@ It is too wide if it has any lines longer than the
largest of
(setq kind (nth 0 form))
(setq name (nth 1 form))
(setq docs (nth 3 form)))
- ;; Here is how one could add lambda's here:
- ;; ('lambda
- ;; (setq kind "") ; can't be "function", unfortunately
- ;; (setq docs (and (stringp (nth 2 form))
- ;; (nth 2 form))))
- )
+ ('lambda
+ (setq kind "") ; can't be "function", unfortunately
+ (setq docs (and (stringp (nth 2 form))
+ (nth 2 form)))))
(when (and (consp name) (eq (car name) 'quote))
(setq name (cadr name)))
(setq name (if name (format " `%s'" name) ""))
diff --git a/test/lisp/emacs-lisp/bytecomp-tests.el
b/test/lisp/emacs-lisp/bytecomp-tests.el
index a760389..4f32e8f 100644
--- a/test/lisp/emacs-lisp/bytecomp-tests.el
+++ b/test/lisp/emacs-lisp/bytecomp-tests.el
@@ -892,10 +892,9 @@ byte-compiled. Run with dynamic binding."
"warn-wide-docstring-define-obsolete-variable-alias.el"
"defvaralias .foo. docstring wider than .* characters")
-;; TODO: We don't yet issue warnings for defuns.
(bytecomp--define-warning-file-test
"warn-wide-docstring-defun.el"
- "wider than .* characters" 'reverse)
+ "wider than .* characters")
(bytecomp--define-warning-file-test
"warn-wide-docstring-defvar.el"
- branch scratch/bug-44858 created (now 35c459f), Stefan Kangas, 2021/09/24
- scratch/bug-44858 2f59fad 1/6: ; Adjust overly long docstrings to fit 80 characters, Stefan Kangas, 2021/09/24
- scratch/bug-44858 4e7c5a6 2/6: Improve filling of generated docstring lines, Stefan Kangas, 2021/09/24
- scratch/bug-44858 e491d97 3/6: Avoid false positives in bytecomp docstring width warning, Stefan Kangas, 2021/09/24
- scratch/bug-44858 35c459f 6/6: Warn about overly long docstring in lambda,
Stefan Kangas <=
- scratch/bug-44858 e4fd496 4/6: Fill some auto-generated docstring lines, Stefan Kangas, 2021/09/24
- scratch/bug-44858 60edb5d 5/6: Avoid warning about long docstring lines in defcustom, Stefan Kangas, 2021/09/24