* bug#50222: Advising a function pollutes its docstring
@ 2021-08-27 3:25 Clément Pit-Claudel
2021-08-27 15:04 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-08-27 15:15 ` Lars Ingebrigtsen
0 siblings, 2 replies; 3+ messages in thread
From: Clément Pit-Claudel @ 2021-08-27 3:25 UTC (permalink / raw)
To: 50222; +Cc: Stefan Monnier
[-- 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 --]
^ permalink raw reply [flat|nested] 3+ messages in thread
* bug#50222: Advising a function pollutes its docstring
2021-08-27 3:25 bug#50222: Advising a function pollutes its docstring Clément Pit-Claudel
@ 2021-08-27 15:04 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-08-27 15:15 ` Lars Ingebrigtsen
1 sibling, 0 replies; 3+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-08-27 15:04 UTC (permalink / raw)
To: Clément Pit-Claudel; +Cc: 50222
> 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
^ permalink raw reply [flat|nested] 3+ messages in thread
* bug#50222: Advising a function pollutes its docstring
2021-08-27 3:25 bug#50222: Advising a function pollutes its docstring Clément Pit-Claudel
2021-08-27 15:04 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-08-27 15:15 ` Lars Ingebrigtsen
1 sibling, 0 replies; 3+ messages in thread
From: Lars Ingebrigtsen @ 2021-08-27 15:15 UTC (permalink / raw)
To: Clément Pit-Claudel; +Cc: 50222, Stefan Monnier
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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2021-08-27 15:15 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-08-27 3:25 bug#50222: Advising a function pollutes its docstring Clément Pit-Claudel
2021-08-27 15:04 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-08-27 15:15 ` Lars Ingebrigtsen
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).