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

Previous Next

Full log

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 44858 <at> debbugs.gnu.org
Subject: Re: bug#44858: [PATCH] Make byte-compiler warn about wide docstrings
Date: Thu, 10 Dec 2020 14:59:16 -0600

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

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.

OK.  The next issue is actually fixing all those docstrings though...

>>> Yes, the autogenerated docstrings should be fixed, too -- mostly by
>>> running them through `fill-paragraph'.
>>
>> I tried that in e.g. define-derived-mode, but fill.el is loaded after
>> derived.el.  So it seems like there is some fun to be had in figuring
>> out the dependencies there...
>
> Yeah, I guess fill.el is a pretty far down in the list of things that
> loadup.el loads?
>
> However, we could make a super-simple function for filling doc
> strings -- doing something that's good enough for that particular task
> shouldn't take more than a few lines.

True.  Please find attached three patches:

1. The original patch adjusted with the heuristic proposed by Eli.

2. Avoid wide docstrings in define-minor-mode.

3. Fixing most wide docstring warnings.

With these three patches applied, around 22 wide docstring warnings
remain in our tree for defvar's.  I found it hard to fix them as I'm not
very familiar with the code in question, and I couldn't just simplify
the wording from the context.

I'm assuming we don't want to push this without fixing those warnings,
so I would really appreciate some help with the remaining couple of
warnings.

Should we perhaps try to get this applied before starting work on
defuns?  Or should I just push a branch for this work?

[0001-Make-byte-compiler-warn-about-wide-docstrings.patch (text/x-diff, attachment)]

[0002-Avoid-wide-doc-strings-in-define-minor-mode.patch (text/x-diff, attachment)]

[0003-Adjust-some-docstrings-to-fit-80-columns.patch (text/x-diff, attachment)]

Previous Next

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