* bug#49007: 28.0.50; "docstring wider than 80" misfire
@ 2021-06-13 17:47 Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-06-14 13:47 ` Lars Ingebrigtsen
0 siblings, 1 reply; 5+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-06-13 17:47 UTC (permalink / raw)
To: 49007
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.")
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#49007: 28.0.50; "docstring wider than 80" misfire
2021-06-13 17:47 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
@ 2021-06-14 13:47 ` Lars Ingebrigtsen
2021-06-14 14:47 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 5+ messages in thread
From: Lars Ingebrigtsen @ 2021-06-14 13:47 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Stefan Kangas, 49007
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#49007: 28.0.50; "docstring wider than 80" misfire
2021-06-14 13:47 ` Lars Ingebrigtsen
@ 2021-06-14 14:47 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-06-15 13:34 ` Lars Ingebrigtsen
0 siblings, 1 reply; 5+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-06-14 14:47 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: Stefan Kangas, 49007
> 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
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#49007: 28.0.50; "docstring wider than 80" misfire
2021-06-14 14:47 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-06-15 13:34 ` Lars Ingebrigtsen
2021-06-15 15:54 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 5+ messages in thread
From: Lars Ingebrigtsen @ 2021-06-15 13:34 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Stefan Kangas, 49007
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* bug#49007: 28.0.50; "docstring wider than 80" misfire
2021-06-15 13:34 ` Lars Ingebrigtsen
@ 2021-06-15 15:54 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 0 replies; 5+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-06-15 15:54 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 49007-done, Stefan Kangas
> I've now pushed a fix for this to Emacs 28 that fixes the test case.
Thanks,
Stefan
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2021-06-15 15:54 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-13 17:47 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
2021-06-14 13:47 ` Lars Ingebrigtsen
2021-06-14 14:47 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-06-15 13:34 ` Lars Ingebrigtsen
2021-06-15 15:54 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).