bug#44858: [PATCH] Make byte-compiler warn about wide docstrings

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@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
Description: Text Data

0002-Avoid-wide-doc-strings-in-define-minor-mode.patch
Description: Text Data

0003-Adjust-some-docstrings-to-fit-80-columns.patch
Description: Text Data