GNU bug report logs - #49007
28.0.50; "docstring wider than 80" misfire

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 49007 in the body.
You can then email your comments to 49007 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; "docstring wider than 80" misfire
Date: Sun, 13 Jun 2021 13:47:27 -0400

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.")

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Stefan Kangas <stefan <at> marxist.se>, 49007 <at> debbugs.gnu.org
Subject: Re: bug#49007: 28.0.50; "docstring wider than 80" misfire
Date: Mon, 14 Jun 2021 15:47:10 +0200

Stefan Monnier <monnier <at> 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

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Stefan Kangas <stefan <at> marxist.se>, 49007 <at> debbugs.gnu.org
Subject: Re: bug#49007: 28.0.50; "docstring wider than 80" misfire
Date: Mon, 14 Jun 2021 10:47:51 -0400

> 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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Stefan Kangas <stefan <at> marxist.se>, 49007 <at> debbugs.gnu.org
Subject: Re: bug#49007: 28.0.50; "docstring wider than 80" misfire
Date: Tue, 15 Jun 2021 15:34:11 +0200

Stefan Monnier <monnier <at> 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

Message #19 received at 49007-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 49007-done <at> debbugs.gnu.org, Stefan Kangas <stefan <at> marxist.se>
Subject: Re: bug#49007: 28.0.50; "docstring wider than 80" misfire
Date: Tue, 15 Jun 2021 11:54:34 -0400

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

Thanks,


        Stefan

Previous Next

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