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

Previous Next

Full log

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

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: Re: bug#66032: [PATCH] Inline advice documentation into advised
 function's docstring, after all
Date: Sat, 23 Sep 2023 21:09:12 +0200

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

Previous Next

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