bug#49007: 28.0.50; "docstring wider than 80" misfire

bug#49007: 28.0.50; "docstring wider than 80" misfire

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Package: Emacs
Version: 28.0.50


Byte-compiling the declaration below complains that

    defalias `rudel-connect' docstring wider than 80 characters

even though it stays within the 80 columns limit.


        Stefan


(cl-defgeneric rudel-connect ((this rudel-protocol-backend) transport
			      info info-callback
			      &optional progress-callback)
  "Create a new connection through TRANSPORT according to the data in INFO.
TRANSPORT has to be an object of a class derived from `rudel-transport'.
INFO has to be a property list.
INFO-CALLBACK has to be a function of two arguments which will be
bound to THIS and INFO.  When called, INFO-CALLBACK should return
a modified version of the INFO argument in which no information
is missing.
When non-nil, PROGRESS-CALLBACK has to be a function that may be
called repeatedly while the connection is established.

Implementations can rely on the fact that the property :session
in INFO contains the `rudel-session' object to which the new
connection will be associated.")

bug#49007: 28.0.50; "docstring wider than 80" misfire

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Byte-compiling the declaration below complains that
>
>     defalias `rudel-connect' docstring wider than 80 characters
>
> even though it stays within the 80 columns limit.
>
>         Stefan
>
> (cl-defgeneric rudel-connect ((this rudel-protocol-backend) transport
> 			      info info-callback
> 			      &optional progress-callback)
>   "Create a new connection through TRANSPORT according to the data in INFO.

Hm...  the warning comes from the arglist being too long, which it
indeed is:

(documentation 'rudel-connect)
=>
"Create a new connection through TRANSPORT according to the data in INFO.
[...]
Implementations can rely on the fact that the property :session
in INFO contains the ‘rudel-session’ object to which the new
connection will be associated.

(fn (THIS rudel-protocol-backend) TRANSPORT INFO INFO-CALLBACK &optional PROGRESS-CALLBACK)"

Which comes from `help--make-usage-docstring'.  However, when displaying
the help, this `fn' bit is then massaged and folded (and placed at the
start).

So perhaps the correct fix here is to have the docstring width checker
ignore those parts?

Any opinions?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49007: 28.0.50; "docstring wider than 80" misfire

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Hm...  the warning comes from the arglist being too long, which it indeed is:
[...]
> (fn (THIS rudel-protocol-backend) TRANSPORT INFO INFO-CALLBACK &optional PROGRESS-CALLBACK)"

Ah, I see.

> So perhaps the correct fix here is to have the docstring width checker
> ignore those parts?

Indeed: the (fn ...) on the last line of a docstring is not really part
of the text, it's just a chunk of data that happens to be stored using
its printed representation (I'm in part to blame for that design choice,
and I don't really like it either, but here we are).


        Stefan

bug#49007: 28.0.50; "docstring wider than 80" misfire

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> So perhaps the correct fix here is to have the docstring width checker
>> ignore those parts?
>
> Indeed: the (fn ...) on the last line of a docstring is not really part
> of the text, it's just a chunk of data that happens to be stored using
> its printed representation (I'm in part to blame for that design choice,
> and I don't really like it either, but here we are).

No matter where we go, there we are.

I've now pushed a fix for this to Emacs 28 that fixes the test case.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49007: 28.0.50; "docstring wider than 80" misfire

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> I've now pushed a fix for this to Emacs 28 that fixes the test case.

Thanks,


        Stefan