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

From: Stefan Kangas <[email-masked]>
Date: Sat, 19 Dec 2020 10:50:33 -0600

Eli Zaretskii <[email-masked]> writes:

> I see nothing wrong with these, so either I'm missing something or
> there's a bug in the code which reports these problems.

Thanks for the fixes.  See my comments below:

>> mh-e/mh-e.el:2827:1: Warning: custom-declare-variable
>>     `mh-invisible-header-fields' docstring wider than 80 characters
>> mh-e/mh-e.el:2850:1: Warning: custom-declare-variable
>>     `mh-invisible-header-fields-default' docstring wider than 80 characters

AFAICT, the offending lines are the ones containing URLs:

line 2839:

`https://sourceforge.net/tracker/index.php?func=detail&aid=1916032&group_id=13357&atid=113357').

line 2683:

`https://sourceforge.net/tracker/index.php?func=detail&aid=1916032&group_id=13357&atid=113357').

I see two issues here:

a) The URL does not easily break over two lines.  I'm not sure what we
   should do.  Add a special case to ignore lines with URLs?

b) The warning doesn't point you to the actually offending line, but to
   the definition containing the docstring.  I'm not sure if this is
   easily fixable or not, or if it's important enough to be worth
   spending time on.

>> net/dbus.el:79:1: Warning: defconst `dbus-interface-peer' docstring wider than
>>     80 characters
>> net/dbus.el:91:1: Warning: defconst `dbus-interface-introspectable' docstring
>>     wider than 80 characters
>> net/dbus.el:102:1: Warning: defconst `dbus-interface-properties' docstring
>>     wider than 80 characters
>> net/dbus.el:128:1: Warning: defconst `dbus-interface-objectmanager' docstring
>>     wider than 80 characters
>> net/dbus.el:148:1: Warning: defconst `dbus-interface-monitoring' docstring
>>     wider than 80 characters

Again we have URLs, like on line 81:

See URL `https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-peer'."

>> org/org-protocol.el:166:1: Warning: custom-declare-variable
>>     `org-protocol-project-alist' docstring wider than 80 characters
>
> I don't see a problem here.

I fixed that one.

>> progmodes/cc-engine.el:183:1: Warning: defvar `c-vsemi-status-unknown-p-fn'
>>     docstring wider than 80 characters
>
> I don't see how I can do anything about this one.

I'm also stomped.  Perhaps we could ask Alan for help with this one.