GNU bug report logs - #44858
[PATCH] Make byte-compiler warn about wide docstrings

Previous Next

Full log

View this message in rfc822 format

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 44858 <at> debbugs.gnu.org
Subject: bug#44858: [PATCH] Make byte-compiler warn about wide docstrings
Date: Wed, 30 Dec 2020 04:07:14 -0800

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>> The problem I saw was basically warnings
>> about symbols only visible after macro expansion, and that warnings
>> would point to entirely the wrong line and column.
>
> Oh, OK, the problem was in the lines/column output, not with detecting
> the doc strings themselves?
>
> Yes, that sounds like a problem, but...  I think we can live with
> inaccurate lines here.

So I tried enabling warnings also for lambda's and here is a fairly
exhaustive list of things that leads to problems:

1. cl-defun

In auth-source-netrc-search:
auth-source.el:1224:11: Warning: docstring wider than 80 characters

Here, the offending line is this autogenerated line:

(fn &rest SPEC &key BACKEND REQUIRE CREATE TYPE MAX HOST USER PORT
&allow-other-keys)

But this line has to be like this if `C-h f' is to show anything but
(&rest spec) for the function parameters.  So should we just add some
special case where we ignore the last line if it matches "^([^)])$"?

2. cl-defstruct

In epg-context--make:
epg.el:197:30: Warning: docstring wider than 80 characters

Here I can't figure out why the docstring is too long.  Using
`macrostep-expand' doesn't reveal why.  Does anyone have any ideas?

3. defclass

These are autogenerated docstrings that I don't trivially see how we can
just wrap as it's the first line that is too long:

In jsonrpc-request:
jsonrpc.el:349:15: Warning: docstring wider than 80 characters

In toplevel form:
cedet/ede/proj-comp.el:71:26: Warning: docstring wider than 80 characters

I suppose we need to rethink these, somehow.

4. semantic

These macros results in wide docstrings in some cases:

- define-overloadable-function
- define-semantic-decoration-style
- define-mode-local-override

5. define-derived-mode

Finally, we have some remaining cases where define-derived-mode leads to
wide docstrings, e.g.:

In newsticker-treeview-list-mode:
net/newst-treeview.el:2031:52: Warning: docstring wider than 80 characters

These should be easy to fix, and I already have an idea for how.

Previous Next

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