GNU bug report logs - #66264
Disable warning about wide doc strings by default

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66264 in the body.
You can then email your comments to 66264 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
To: Emacs Bug Report <bug-gnu-emacs <at> gnu.org>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, "T.V Raman" <raman <at> google.com>
Subject: Disable warning about wide doc strings by default
Date: Fri, 29 Sep 2023 14:59:09 +0200

[Message part 1 (text/plain, inline)]

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.

[docstrings-wide.diff (application/octet-stream, attachment)]

Message #8 received at 66264 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mattias Engdegård <mattias.engdegard <at> gmail.com>
Cc: raman <at> google.com, stefankangas <at> gmail.com, 66264 <at> debbugs.gnu.org
Subject: Re: bug#66264: Disable warning about wide doc strings by default
Date: Fri, 29 Sep 2023 18:43:51 +0300

> Cc: Stefan Kangas <stefankangas <at> gmail.com>, "T.V Raman" <raman <at> google.com>
> From: Mattias Engdegård <mattias.engdegard <at> gmail.com>
> Date: Fri, 29 Sep 2023 14:59:09 +0200
> 
> This is a proposal to disable the warning about doc string line length by default.

Thanks, but I'm against this change.  It has been, and continues to
be, tremendously useful in making sure our doc strings are in a good
shape.  I don't see how leaving this on only in "Emacs builds" is TRT,
since this means ELPA packages will be exempt from the same scrutiny,
and it also means that byte-compiling a file manually (i.e. not via
lisp/Makefile) will not produce this warning.  I think the small
annoyance of some people about overly-long doc strings produced by
macros is not a sufficient reason to turn this off by default, and
that those who are annoyed can turn it off in their configurations.

Message #11 received at 66264 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: mattias.engdegard <at> gmail.com, 66264 <at> debbugs.gnu.org, stefankangas <at> gmail.com,
 raman <at> google.com
Subject: Re: bug#66264: Disable warning about wide doc strings by default
Date: Sat, 30 Sep 2023 04:17:42 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > This is a proposal to disable the warning about doc string line length by default.

  > Thanks, but I'm against this change.  It has been, and continues to
  > be, tremendously useful in making sure our doc strings are in a good
  > shape.

I agree.  The point of a warning is to remind programmers to write
things the way that will give good results, and the width of a doc
string is part of what determines whether it gives good results
when users look at it.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #20 received at 66264-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Richard Stallman <rms <at> gnu.org>
Cc: 66264-done <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 mattias.engdegard <at> gmail.com, raman <at> google.com
Subject: Re: bug#66264: Disable warning about wide doc strings by default
Date: Sun, 23 Feb 2025 01:19:38 +0000

Richard Stallman <rms <at> gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > > This is a proposal to disable the warning about doc string line length by default.
>
>   > Thanks, but I'm against this change.  It has been, and continues to
>   > be, tremendously useful in making sure our doc strings are in a good
>   > shape.
>
> I agree.  The point of a warning is to remind programmers to write
> things the way that will give good results, and the width of a doc
> string is part of what determines whether it gives good results
> when users look at it.

FWIW, I'd be in favor of making this change.

However, it seems like we don't have a consensus on this, so I don't
think we'll make much more progress here.  I'm therefore closing this
bug report.  Sorry.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.