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

Previous Next

Full log

View this message in rfc822 format

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 66032 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all
Date: Sat, 23 Sep 2023 10:07:48 +0200

Stefan Monnier <monnier <at> 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.

Previous Next

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