From: "Clément Pit-Claudel" <clement.pitclaudel@live.com>
To: 50222@debbugs.gnu.org
Cc: Stefan Monnier <monnier@iro.umontreal.ca>
Subject: bug#50222: Advising a function pollutes its docstring
Date: Thu, 26 Aug 2021 23:25:15 -0400 [thread overview]
Message-ID: <DB7P192MB0313584FA4443D159BD21818EEC89@DB7P192MB0313.EURP192.PROD.OUTLOOK.COM> (raw)
[-- 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 --]
next reply other threads:[~2021-08-27 3:25 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-27 3:25 Clément Pit-Claudel [this message]
2021-08-27 15:04 ` bug#50222: Advising a function pollutes its docstring Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-08-27 15:15 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=DB7P192MB0313584FA4443D159BD21818EEC89@DB7P192MB0313.EURP192.PROD.OUTLOOK.COM \
--to=clement.pitclaudel@live.com \
--cc=50222@debbugs.gnu.org \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).