bug#50222: Advising a function pollutes its docstring

bug#50222: Advising a function pollutes its docstring

[Clément Pit-Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1266 bytes --]

Hi all,

Advising a function changes the first line of its docstring, which breaks packages that use the first line of the docstring to display a short piece of information about a function.  I noticed this issue while playing with the "shortdoc" feature. For example:

M-x shortdoc-display-group RET process:

  (make-process &rest args)
    Start a program in a subprocess.  Return the process object for it.
    (make-process :name "foo" :command '("cat" "/tmp/foo"))

But after running (advice-add 'make-process :before (lambda (&rest args))):

  (make-process &rest args)
    This function has :before advice: No documentation
    (make-process :name "foo" :command '("cat" "/tmp/foo"))
      eg. ⇒ #<process foo>

It would be nice to place the bit of text about advice somewhere else — maybe with the indented paragraph of the docs that says when the function was introduced and which group contains the relevant docs?

  (make-process &rest ARGS)

    Other relevant functions are documented in the process group.
    Probably introduced at or before Emacs version 25.1.
    // HERE? //

  This function has :before advice: No documentation

  Start a program in a subprocess.  Return the process object for it.

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 840 bytes --]

bug#50222: Advising a function pollutes its docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Advising a function changes the first line of its docstring, which
> breaks packages that use the first line of the docstring to display
> a short piece of information about a function.  I noticed this issue
> while playing with the "shortdoc" feature. For example:

Indeed, we should probably use `help-fns-describe-function-functions`
instead of the `function-documentation` property in `nadvice.el`.


        Stefan

bug#50222: Advising a function pollutes its docstring

[Lars Ingebrigtsen]

Clément Pit-Claudel <clement.pitclaudel@live.com> writes:

> It would be nice to place the bit of text about advice somewhere else
> — maybe with the indented paragraph of the docs that says when the
> function was introduced and which group contains the relevant docs?

I don't think putting it in the indented bit will work well, because the
advice may have multi-line doc strings...

So changed it to just put the advice doc at the end of the doc string in
Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no