bug#19033: 25.0.50; (elisp) `Advising Named Functions' does not describe FUNCTION

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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