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

Previous Next

Full log

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

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Inline advice documentation into advised function's
 docstring, after all
Date: Sat, 16 Sep 2023 14:57:33 +0200

[Message part 1 (text/plain, inline)]

Severity: wishlist
X-Debbugs-CC: drew.adams <at> oracle.com, monnier <at> 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 (text/x-patch, attachment)]

Previous Next

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