GNU bug report logs - #66032
[PATCH] Inline advice documentation into advised function's docstring, after all

Previous Next

Full log

View this message in rfc822 format

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 66032 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all
Date: Sat, 16 Sep 2023 19:15:27 +0200

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

>> But at least on one occasion Stefan has asked for a patch, and I
>> haven't seen yet patches that got declined.
>
> It does happen, tho.

From your detailed comments (thanks for those) I understand that a patch
for *this* bug would be, in principle, still welcome.

I'll re-comment only where I think it's needed, everything else I try to
implement as you seem to suggest.

> I got used to the single line where I have to click to get more info,
> so I'm not the target audience, but see comments below.

My advices' docstrings all start with verb in 3rd person singular, and
that looks awful if viewed standalone.  (Showing off my standard
adherence here.)  More seriously, I have been thinking about a
customizable option to control the inclusion of advice docstrings, but
nadvice.el seems to be too infrastructure-y for that.

> The main problem I see, tho, is how to clearly "delimit" the
> docstring.  Maybe we should indent the advice's docstring by two
> spaces or so?

Probably OK, but I'm afraid that lines get too long, then.  OTOH, advice
docstrings are probably not that lengthy, in general.  I'll give it a
try and consider alternatives as well.

Do you think this docstring generation should be covered by ERT tests?

Previous Next

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