GNU bug report logs - #50222
Advising a function pollutes its docstring

Previous Next

Full log

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

From: Clément Pit-Claudel <clement.pitclaudel <at> live.com>
To: bug-gnu-emacs <bug-gnu-emacs <at> gnu.org>
Subject: Advising a function pollutes its docstring
Date: Thu, 26 Aug 2021 23:25:15 -0400

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

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.

[OpenPGP_signature (application/pgp-signature, attachment)]

Previous Next

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