From 0e15f9b48da2d0b6c2a1ddde8d616ce537b19aa0 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Tue, 9 Aug 2005 11:59:22 +0000 Subject: [PATCH] (Advising Functions): Explain when to use advice and when to use a hook. --- lispref/advice.texi | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/lispref/advice.texi b/lispref/advice.texi index 2006474fc61..e741300b91d 100644 --- a/lispref/advice.texi +++ b/lispref/advice.texi @@ -8,7 +8,7 @@ @cindex advising functions The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a clean method +a function, by @dfn{advising the function}. This is a cleaner method for a library to customize functions defined within Emacs---cleaner than redefining the whole function. @@ -23,8 +23,20 @@ are not the same thing. @strong{Usage Note:} Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior -for new calls, or for key bindings, it is cleaner to define a new -function (or a new command) which uses the existing function. +for new calls, or for key bindings, you should define a new function +(or a new command) which uses the existing function. + + @strong{Usage note:} Advising a function can cause confusion in +debugging, since people who debug calls to the original function may +not notice that it has been modified with advice. Therefore, if you +have the possibility to change the code of that function (or ask +someone to do so) to run a hook, please solve the problem that way. +Advice should be reserved for the cases where you cannot get the +function changed. + + In particular, this means that a file in Emacs should not put advice +on a function in Emacs. There are currently a few exceptions to this +convention, but we aim to correct them. @menu * Simple Advice:: A simple example to explain the basics of advice. -- 2.39.2