From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Newsgroups: gmane.emacs.bugs Subject: bug#66264: Disable warning about wide doc strings by default Date: Fri, 29 Sep 2023 14:59:09 +0200 Message-ID: Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.15\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_97403ADE-D3D7-4C8A-BAF7-13A0BC5D7792" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21785"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Stefan Kangas , "T.V Raman" To: 66264@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Sep 29 15:00:07 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qmD6E-0005QX-5s for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 Sep 2023 15:00:06 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qmD60-00045E-0h; Fri, 29 Sep 2023 08:59:52 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qmD5x-000432-7Q for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 08:59:49 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qmD5w-0001TP-Pj for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 08:59:48 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qmD6B-0005a8-3T for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 09:00:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 29 Sep 2023 13:00:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 66264 X-GNU-PR-Package: emacs X-Debbugs-Original-To: Emacs Bug Report Original-Received: via spool by submit@debbugs.gnu.org id=B.169599239221402 (code B ref -1); Fri, 29 Sep 2023 13:00:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 29 Sep 2023 12:59:52 +0000 Original-Received: from localhost ([127.0.0.1]:55501 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmD5u-0005Z1-4g for submit@debbugs.gnu.org; Fri, 29 Sep 2023 08:59:52 -0400 Original-Received: from lists.gnu.org ([2001:470:142::17]:55710) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qmD5o-0005Yi-Eb for submit@debbugs.gnu.org; Fri, 29 Sep 2023 08:59:44 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qmD5U-0003ao-12 for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 08:59:20 -0400 Original-Received: from mail-lj1-x22c.google.com ([2a00:1450:4864:20::22c]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qmD5P-0001RA-6N for bug-gnu-emacs@gnu.org; Fri, 29 Sep 2023 08:59:19 -0400 Original-Received: by mail-lj1-x22c.google.com with SMTP id 38308e7fff4ca-2bfed7c4e6dso228581301fa.1 for ; Fri, 29 Sep 2023 05:59:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1695992352; x=1696597152; darn=gnu.org; h=to:cc:date:message-id:subject:mime-version:from:sender:from:to:cc :subject:date:message-id:reply-to; bh=eCMYUygds/I5aR/l0JOrbPKdDav3T5f0h06mFeEz6Lc=; b=KPBF3mURBA14Yz1fkjZWSlnCGKjON1TLAX0N00XQ3MD7UDhM4RlYbZpJMID6o4yQkd 5KsKAuSSRf5S9+Fjw1mm+g2bHGygD92pYmQKWVZU7EHJPsECLLkRRPeCxcts9onGwP4H noHhoiiVZhFXfea+AAW1q0ozp+Q5lkyajApefF+tv0HAe5z0+qOlZ6Q8mQ+L3Gcrh2bT 7R6/KoeMH0jcat91uCI0ZKa06smvvbvZ3+QKgSg2ZbfIR6B3BRmkUOgs8zYH/FKMgbeb G6hCpCckPBlARxR8qt0s+Lq8PH5lXzZJ1TMu9d/bHMD9dr+ZWNfq7JK8aEsNFFjYzoi9 Kfsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695992352; x=1696597152; h=to:cc:date:message-id:subject:mime-version:from:sender :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=eCMYUygds/I5aR/l0JOrbPKdDav3T5f0h06mFeEz6Lc=; b=WIbqX0LA5j73zdgHCzuddBUyHwB507CNiA/BpdkQjqLSgYeaXFkLGyK6t5XAGk6UDf OtOHvK+HXS1lIwfFwb7fz1TKK2FdNDFafcP9FIKekjB0hPfhOQA3d7TT2Uv7W1fNjMXK ldKIL7St2WzzrcyVlmOZkBhuOT+WwkrH6hS7nt8UZXMo/eYIlUI5M72GAAVWNgZcHVeB 9wsc1l33mtswAe74ne+83uDoPYc4Hd9SDrPyToFUGGbH3vsmt3TTlAzut1F0Gi/j9BHf I6UonvAtT2eVNeKU37W53JaH7TjDpIyPd4I7yXKXFKeeZ86DhvRyOrmCU0m9DVla1r1r xyDg== X-Gm-Message-State: AOJu0YwI+mNXsjgRSxRhxsV8L4DdcJCs3vXugKDcGcxGXxw7B+KY6iDR CsXcdBD6nNgUuuy6h+EhuBzj16Mj9VGbMA== X-Google-Smtp-Source: AGHT+IHXM09TjhYt47f+gWkjOMmL/jgzK4acub6sFrqEM9ZvdlKWcHm8UNhUQPmfaYAoyzZaZNTuOA== X-Received: by 2002:a05:6512:34c4:b0:503:258f:fd15 with SMTP id w4-20020a05651234c400b00503258ffd15mr3513879lfr.20.1695992351625; Fri, 29 Sep 2023 05:59:11 -0700 (PDT) Original-Received: from smtpclient.apple (c188-150-165-235.bredband.tele2.se. [188.150.165.235]) by smtp.gmail.com with ESMTPSA id w17-20020ac254b1000000b004fe8593b67fsm3496761lfk.107.2023.09.29.05.59.10 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Fri, 29 Sep 2023 05:59:10 -0700 (PDT) X-Mailer: Apple Mail (2.3654.120.0.1.15) Received-SPF: pass client-ip=2a00:1450:4864:20::22c; envelope-from=mattias.engdegard@gmail.com; helo=mail-lj1-x22c.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:271489 Archived-At: --Apple-Mail=_97403ADE-D3D7-4C8A-BAF7-13A0BC5D7792 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii This is a proposal to disable the warning about doc string line length = by default. While it is a useful warning, it does not actually indicate that = anything may be wrong in the code, nor that the doc string would risk = being misinterpreted by the user. It is rather a stylistic complaint, = such as the ones produced by checkdoc. There have been complaints about the warning being difficult to avoid in = code where the doc string is generated by macros, sometimes outside the = control of the programmer. See = https://lists.gnu.org/archive/html/emacs-devel/2023-09/msg01326.html for = one such recent discussion. For this reason I'm proposing that it be disabled by default but remain = enabled in builds of Emacs itself, like the warning about curved single = quotes. Patch attached. --Apple-Mail=_97403ADE-D3D7-4C8A-BAF7-13A0BC5D7792 Content-Disposition: attachment; filename=docstrings-wide.diff Content-Type: application/octet-stream; x-unix-mode=0644; name="docstrings-wide.diff" Content-Transfer-Encoding: 7bit diff --git a/etc/NEWS b/etc/NEWS index 97ebc9a5de4..7e29a987c76 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1220,6 +1220,10 @@ name 'ignored-return-value'. The warning will only be issued for calls to functions declared 'important-return-value' or 'side-effect-free' (but not 'error-free'). +--- +*** The warning about too-wide doc strings is now disabled by default. +It can be enabled by setting 'byte-compile-warning-types' to 'all'. + +++ ** New function declaration and property 'important-return-value'. The declaration '(important-return-value t)' sets the diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el index 387d7ef4de1..2fcadc19a5a 100644 --- a/lisp/emacs-lisp/bytecomp.el +++ b/lisp/emacs-lisp/bytecomp.el @@ -295,7 +295,7 @@ byte-compile-warning-types '(redefine callargs free-vars unresolved obsolete noruntime interactive-only make-local mapcar constants suspicious lexical lexical-dynamic - docstrings docstrings-non-ascii-quotes not-unused + docstrings docstrings-wide docstrings-non-ascii-quotes not-unused empty-body) "The list of warning types used when `byte-compile-warnings' is t.") (defcustom byte-compile-warnings t @@ -322,12 +322,15 @@ byte-compile-warnings is likely to be a mistake not-unused warning about using variables with symbol names starting with _. constants let-binding of, or assignment to, constants/nonvariables. - docstrings docstrings that are too wide (longer than - `byte-compile-docstring-max-column' or - `fill-column' characters, whichever is bigger) or - have other stylistic issues. - docstrings-non-ascii-quotes docstrings that have non-ASCII quotes. - This depends on the `docstrings' warning type. + docstrings various docstring stylistic issues, such as incorrect use + of single quotes + docstrings-wide + docstrings that are too wide, containing lines longer than both + `byte-compile-docstring-max-column' and `fill-column' characters. + Only enabled when `docstrings' also is. + docstrings-non-ascii-quotes + docstrings that have non-ASCII quotes. + Only enabled when `docstrings' also is. suspicious constructs that usually don't do what the coder wanted. empty-body body argument to a special form or macro is empty. mutate-constant @@ -345,7 +348,7 @@ byte-compile-warnings byte-compile-warning-types)))) (defconst byte-compile--emacs-build-warning-types - '(docstrings-non-ascii-quotes) + '(docstrings-non-ascii-quotes docstrings-wide) "List of warning types that are only enabled during Emacs builds. This is typically either warning types that are being phased in (but shouldn't be enabled for packages yet), or that are only relevant @@ -1753,7 +1756,8 @@ byte-compile-docstring-style-warn (setq name (cadr name))) (setq name (if name (format " `%s' " name) "")) (when (and kind docs (stringp docs)) - (when (byte-compile--wide-docstring-p docs col) + (when (and (byte-compile-warning-enabled-p 'docstrings-wide) + (byte-compile--wide-docstring-p docs col)) (byte-compile-warn-x name "%s%sdocstring wider than %s characters" diff --git a/test/lisp/emacs-lisp/bytecomp-tests.el b/test/lisp/emacs-lisp/bytecomp-tests.el index e644417c3d4..45cf8b577ba 100644 --- a/test/lisp/emacs-lisp/bytecomp-tests.el +++ b/test/lisp/emacs-lisp/bytecomp-tests.el @@ -925,20 +925,21 @@ bytecomp-tests--warnings ;; Should not warn that mt--test2 is not known to be defined. (should-not (re-search-forward "my--test2" nil t)))) -(defun bytecomp--with-warning-test (re-warning form) +(defun bytecomp--with-warning-test (re-warning form &optional warnings) (declare (indent 1)) (with-current-buffer (get-buffer-create "*Compile-Log*") (let ((inhibit-read-only t)) (erase-buffer)) (ert-info ((prin1-to-string form) :prefix "form: ") - (let ((text-quoting-style 'grave)) + (let ((text-quoting-style 'grave) + (byte-compile-warnings (or warnings t))) (bytecomp-tests--with-fresh-warnings (byte-compile form))) (ert-info ((prin1-to-string (buffer-string)) :prefix "buffer: ") (should (re-search-forward (string-replace " " "[ \n]+" re-warning))))))) -(defun bytecomp--without-warning-test (form) - (bytecomp--with-warning-test "\\`\\'" form)) +(defun bytecomp--without-warning-test (form &optional warnings) + (bytecomp--with-warning-test "\\`\\'" form warnings)) (ert-deftest bytecomp-warn--ignore () (bytecomp--with-warning-test "unused" @@ -966,39 +967,49 @@ bytecomp-tests--docstring (ert-deftest bytecomp-warn-wide-docstring/defconst () (bytecomp--with-warning-test "defconst.*foo.*wider than.*characters" - `(defconst foo t ,bytecomp-tests--docstring))) + `(defconst foo t ,bytecomp-tests--docstring) + 'all)) (ert-deftest bytecomp-warn-wide-docstring/defvar () (bytecomp--with-warning-test "defvar.*foo.*wider than.*characters" - `(defvar foo t ,bytecomp-tests--docstring))) + `(defvar foo t ,bytecomp-tests--docstring) + 'all)) (ert-deftest bytecomp-warn-wide-docstring/cl-defsubst () (bytecomp--without-warning-test `(cl-defsubst short-name () - "Do something.")) + "Do something." + 'all)) (bytecomp--without-warning-test `(cl-defsubst long-name-with-less-80-characters-but-still-quite-a-bit () - "Do something.")) + "Do something.") + 'all) (bytecomp--with-warning-test "wider than.*characters" `(cl-defsubst long-name-with-more-than-80-characters-yes-this-is-a-very-long-name-but-why-not!! () - "Do something."))) + "Do something.") + 'all)) (ert-deftest bytecomp-warn-wide-docstring/cl-defstruct () (bytecomp--without-warning-test `(cl-defstruct short-name - field)) + field) + 'all) (bytecomp--without-warning-test `(cl-defstruct short-name - long-name-with-less-80-characters-but-still-quite-a-bit)) + long-name-with-less-80-characters-but-still-quite-a-bit) + 'all) (bytecomp--without-warning-test `(cl-defstruct long-name-with-less-80-characters-but-still-quite-a-bit - field)) + field) + 'all) (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!!)) + long-name-with-more-than-80-characters-yes-this-is-a-very-long-name-but-why-not!!) + 'all) (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))) + field) + 'all)) (ert-deftest bytecomp-warn-quoted-condition () (bytecomp--with-warning-test @@ -1060,11 +1071,13 @@ bytecomp-warn-dodgy-args-memq (bytecomp--with-warning-test (msg2 "integer") (form2 #x10000000000)) (bytecomp--with-warning-test (msg2 "float") (form2 1.0)))))) -(defmacro bytecomp--define-warning-file-test (file re-warning &optional reverse) +(defmacro bytecomp--define-warning-file-test (file re-warning + &optional reverse warnings) `(ert-deftest ,(intern (format "bytecomp/%s" file)) () (with-current-buffer (get-buffer-create "*Compile-Log*") (let ((inhibit-read-only t)) (erase-buffer)) - (byte-compile-file ,(ert-resource-file file)) + (let ((byte-compile-warnings ,(or warnings t))) + (byte-compile-file ,(ert-resource-file file))) (ert-info ((buffer-string) :prefix "buffer: ") (,(if reverse 'should-not 'should) (re-search-forward ,re-warning nil t)))))) @@ -1170,71 +1183,71 @@ "warn-variable-setq-odd.el" (bytecomp--define-warning-file-test "warn-wide-docstring-autoload.el" - "autoload .foox. docstring wider than .* characters") + "autoload .foox. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-custom-declare-variable.el" - "custom-declare-variable .foo. docstring wider than .* characters") + "custom-declare-variable .foo. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-defalias.el" - "defalias .foo. docstring wider than .* characters") + "defalias .foo. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-defconst.el" - "defconst .foo-bar. docstring wider than .* characters") + "defconst .foo-bar. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-define-abbrev-table.el" - "define-abbrev-table .foo. docstring wider than .* characters") + "define-abbrev-table .foo. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-define-obsolete-function-alias.el" - "defalias .foo. docstring wider than .* characters") + "defalias .foo. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-define-obsolete-variable-alias.el" - "defvaralias .foo. docstring wider than .* characters") + "defvaralias .foo. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-defun.el" - "Warning: docstring wider than .* characters") + "Warning: docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-defvar.el" - "defvar .foo-bar. docstring wider than .* characters") + "defvar .foo-bar. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-defvaralias.el" - "defvaralias .foo-bar. docstring wider than .* characters") + "defvaralias .foo-bar. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-ignore-fill-column.el" - "defvar .foo-bar. docstring wider than .* characters" 'reverse) + "defvar .foo-bar. docstring wider than .* characters" 'reverse 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-ignore-function-signature.el" - "defvar .foo-bar. docstring wider than .* characters" 'reverse) + "defvar .foo-bar. docstring wider than .* characters" 'reverse 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-ignore-override.el" - "defvar .foo-bar. docstring wider than .* characters" 'reverse) + "defvar .foo-bar. docstring wider than .* characters" 'reverse 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-ignore-substitutions.el" - "defvar .foo-bar. docstring wider than .* characters" 'reverse) + "defvar .foo-bar. docstring wider than .* characters" 'reverse 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-ignore.el" - "defvar .foo-bar. docstring wider than .* characters" 'reverse) + "defvar .foo-bar. docstring wider than .* characters" 'reverse 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-multiline-first.el" - "defvar .foo-bar. docstring wider than .* characters") + "defvar .foo-bar. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "warn-wide-docstring-multiline.el" - "defvar .foo-bar. docstring wider than .* characters") + "defvar .foo-bar. docstring wider than .* characters" nil 'all) (bytecomp--define-warning-file-test "nowarn-inline-after-defvar.el" --Apple-Mail=_97403ADE-D3D7-4C8A-BAF7-13A0BC5D7792--