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

[Jens Schmidt]

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

>> The documentation of the *function's advices*, however, is handled by
>> some function on `help-fns-describe-function-functions'.  By default we
>> add a function `advice-describe-function-advices' (for you) but offer an
>> alternative one `advice-describe-detailed-function-advices' (for me and
>> others who have been asking for inlined docstrings).  In principle this
>> works, as I have confirmed with a very rough prototype.
>
> That's an option as well (and it comes with the advantage that the list
> of advice can come after things like obsoletion info rather than before,
> which would be an improvement as well).

Exactly that was how I learned about `help-fns-d-f-f': The obsoletion
information currently being "misplaced" w.r.t. the advice documentation,
which gets more pronounced when the advice documentation gets longer.

> I don't see any reason to reduce what is displayed by default (at least,
> nobody has asked for that, AFAIK), so the question is how to make it
> sufficiently easy to switch to a more detailed output.  `remove-hook` of
> the default followed by `add-hook` of the other seems
> rather inconvenient.

I think anything more customizable than that would require a new
customization group, a defcustom, etc, which is probably too much effort
for a rather arcane feature.  So I will go simply for a more detailed
output by default on `help-fns-describe-function-functions'.

Here is one minor obstacle, though: The documentation of `h-f-d-f-f'
says:

  By convention they should indent their output by 2 spaces.

I think it is OK to break that convention for the advice headlines,
which I would like to start at column zero to set them off visibly
(and make them usable for outlining).