Subject: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all

From: Stefan Monnier <[email-masked]>
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