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

[Jens Schmidt]

Severity: wishlist
X-Debbugs-CC: drew.adams@oracle.com, monnier@iro.umontreal.ca

I'm aware that I'm late to the party (got unstuck from Emacs 23
only recently) and that there have been some reports on that
already (bug#14734 and merged).

But at least on one occasion Stefan has asked for a patch, and I
haven't seen yet patches that got declined.  So here is one, so
far the plain code patch only, without NEWS, tests, etc.  It was
actually easier to implement than I thought, I hope I haven't
overseen any edge cases.

Here are two examples of how the generated documentation looks
like.  The former shows documentation of a legacy-advised
function, the latter shows documentation of one of Stefan's
test advice to demonstrate that these cases are handled as well.

------------------------- snip -------------------------
ediff-quit is an interactive byte-compiled Lisp function in
‘ediff-util.el’.

(ediff-quit REVERSE-DEFAULT-KEEP-VARIANTS)

Finish an Ediff session and exit Ediff.
[...]
With prefix argument REVERSE-DEFAULT-KEEP-VARIANTS, temporarily
reverse the meaning of this variable.

<font-lock-warning-face>This function is advised.</f-l-w-f>

This function has :around advice: ‘ad-Advice-ediff-quit’
Does not ask any stupid questions.

Pops to buffer A.

[back]
------------------------- snip -------------------------

------------------------- snip -------------------------
sm-test1 is a Lisp macro.

(sm-test1 A)

<font-lock-warning-face>This function is advised.</f-l-w-f>

This macro has :override advice: No documentation

This is an :override advice, which means that ‘sm-test1’ isn’t
run at all, and the documentation below may be irrelevant.

This macro has :around advice: No documentation

[back]
------------------------- snip -------------------------

What do you think?

0001-Improve-documentation-of-advised-macros-or-functions.patch
Description: Text Data