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

Previous Next

Full log

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

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

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

It's been requested a few times, so we may as well, yes.
I think ideally it should be fold(ed|able), but we don't have the
infrastructure for that yet.

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

Maybe a halfway point is to include only the first line of the
advice's docstring?

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

We could consider this as a bug in the advice's docstring
(i.e. decide&document that advices' docstrings should use fewer columns
because they'll be displayed indented).

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

ERT tests are always welcome,


        Stefan

Previous Next

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