Subject: bug#76528: 30; Advising functions can cause docstring to be lost

From: Stefan Monnier <[email-masked]>
Date: Tue, 25 Feb 2025 15:38:09 -0500

>>> Stefan, any comments?
>>
>> Just that it's directly related to this part of the code in
>> `nadvice.el`:
>>
>>     ;; FIXME: We could use a defmethod on `function-documentation' instead,
>>     ;; except when (autoloadp nf)!
>>     (put symbol 'function-documentation `(advice--make-docstring ',symbol))
>
> Transient (transient--wrap-command) has to advise every command that is
> invoked while the menu is active, so this has the potential to cause a
> lot of damage.

Indeed.  🙁
I guess this hasn't been noticed until now because
`function-documentation` is not used very often.

> How should I deal with that?  Maybe essentially?:

Well, we should fix it in `nadvice.el`, of course.  But for
compatibility with older Emacsen...

>   (let ((docstr (documentation this-command))
>         (advice (lambda (fn &rest args) (apply fn args))))
>     (advice-add this-command :around advice)
      [...]
>     (advice-remove this-command advice)
>     (unless (equal (documentation this-command) docstr)
>       (put this-command 'function-documentation docstr)))

That sounds about right, tho you'd have to replace the `(documentation
this-command)` with `(get this-command 'function-documentation)`.

Somewhat related question: can it happen that the command (stored in
`this-command`, apparently) is not a symbol, and if so how do you
wrap it?

        Stefan