GNU bug report logs - #19033
Manual: (elisp) `Advising Named Functions' does not describe FUNCTION

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 19033 in the body.
You can then email your comments to 19033 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; (elisp) `Advising Named Functions' does not describe FUNCTION
Date: Wed, 12 Nov 2014 09:11:47 -0800 (PST)

This node sends you off to node `Core Advising Primitives' for
information about parameters WHERE and PROPS.

That's bad enough, since `Advising Named Functions' is intended as the
MAIN entry point for advising functions:

  "But you should use `advice-add' and `advice-remove' for that instead."

But `Advising Named Functions' tells you nothing about FUNCTION.  In
particular, it does not tell you what its signature must be or must fit.

Worse still, neither does node `Core Advising Primitives' tell you
anything about the signature of FUNCTION!  So it would not even be
enough to send readers to that node for information about FUNCTION,
as we do now for WHERE and PROPS.

What must FUNCTION accept as argument(s)?  What must it return?
If there are no restrictions on its signature, then say so.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm <at> gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 19033 <at> debbugs.gnu.org
Subject: Re: bug#19033: 25.0.50; (elisp) `Advising Named Functions' does not
 describe FUNCTION
Date: Wed, 09 Oct 2019 03:46:14 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> This node sends you off to node `Core Advising Primitives' for
> information about parameters WHERE and PROPS.
>
> That's bad enough, since `Advising Named Functions' is intended as the
> MAIN entry point for advising functions:
>
>   "But you should use `advice-add' and `advice-remove' for that instead."
>
> But `Advising Named Functions' tells you nothing about FUNCTION.  In
> particular, it does not tell you what its signature must be or must fit.
>
> Worse still, neither does node `Core Advising Primitives' tell you
> anything about the signature of FUNCTION!  So it would not even be
> enough to send readers to that node for information about FUNCTION,
> as we do now for WHERE and PROPS.
>
> What must FUNCTION accept as argument(s)?  What must it return?
> If there are no restrictions on its signature, then say so.

If I understand correctly, what you want is that the

@defmac add-function where place function &optional props

in

@node Core Advising Primitives

should describe what parameters @var{function} takes in that macro.
That is indeed not described in that node, presumably because it's
complicated.  Instead, we're directed to

@var{where} determines how @var{function} is composed with the
existing function, e.g., whether @var{function} should be called before, or
after the original function.  @xref{Advice Combinators}, for the list of
available ways to compose the two functions.

where we find stuff like

@table @code
@item :before
Call @var{function} before the old function.  Both functions receive the
same arguments

I think that makes sense -- trying to say anything about the parameters
before talking about @var{where} is pretty futile, because @var{where}
decides what parameters the function will receive.

So I don't see anything to fix here, and I'm closing this bug report.

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

Previous Next

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