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

[Jens Schmidt]

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

> I think ideally it should be fold(ed|able), but we don't have the
> infrastructure for that yet.

With advice documentation looking like this:

------------------------- snip -------------------------
* :after advice ‘js-test-3’

  Doc string js-doc-3.

* :around advice ‘js-test-2’

  Doc string js-doc-2.

* :before advice ‘js-test-1’

  Doc string js-doc-1.
------------------------- snip -------------------------

and `outline-minor-mode' we can get even that.  Downsides:

- The documentation of function `*' looks funny when folded.

- The "[back] [forward]" navigation buttons get folded.

NB: I don't want to switch on `o-m-m' by default in *Help* buffers - we
could just advertise that somewhere.


But here is one other idea I wanted to discuss, which could both
simplify that whole business *and* make it to some extent customizable:

I propose to limit the docstring generation in `advice--make-docstring'
to something like this:

------------------------- snip -------------------------
js-test-0 is a Lisp function.

<f-l-w-f>This function is advised.</f-l-w-f>

(js-test-0 &rest _)

Doc string js-doc-0.
------------------------- snip -------------------------

that is, just include the *original function's docstring* and
some warning in it.

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.


There are some pros and cons to this, but before I go into details I
wanted to get your opinion on that.