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

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

[Drew Adams]

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@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

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