diff options
Diffstat (limited to 'doc/lispref/functions.texi')
| -rw-r--r-- | doc/lispref/functions.texi | 66 |
1 files changed, 43 insertions, 23 deletions
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index eac5b91e76a..ff635fc54b2 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -498,13 +498,12 @@ indentation of the following lines is inside the string; what looks nice in the source code will look ugly when displayed by the help commands. - You may wonder how the documentation string could be optional, since -there are required components of the function that follow it (the body). -Since evaluation of a string returns that string, without any side effects, -it has no effect if it is not the last form in the body. Thus, in -practice, there is no confusion between the first form of the body and the -documentation string; if the only body form is a string then it serves both -as the return value and as the documentation. + A documentation string must always be followed by at least one Lisp +expression; otherwise, it is not a documentation string at all but the +single expression of the body and used as the return value. +When there is no meaningful value to return from a function, it is +standard practice to return @code{nil} by adding it after the +documentation string. The last line of the documentation string can specify calling conventions different from the actual function arguments. Write @@ -771,9 +770,12 @@ explicitly in the source file being loaded. This is because By contrast, in programs that manipulate function definitions for other purposes, it is better to use @code{fset}, which does not keep such records. @xref{Function Cells}. + +If the resulting function definition chain would be circular, then +Emacs will signal a @code{cyclic-function-indirection} error. @end defun -@defun function-alias-p object &optional noerror +@defun function-alias-p object Checks whether @var{object} is a function alias. If it is, it returns a list of symbols representing the function alias chain, else @code{nil}. For instance, if @code{a} is an alias for @code{b}, and @@ -784,9 +786,8 @@ a list of symbols representing the function alias chain, else @result{} (b c) @end example -If there's a loop in the definitions, an error will be signaled. If -@var{noerror} is non-@code{nil}, the non-looping parts of the chain is -returned instead. +There is also a second, optional argument that is obsolete and has no +effect. @end defun You cannot create a new primitive function with @code{defun} or @@ -1573,6 +1574,9 @@ is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}): If you wish to use @code{fset} to make an alternate name for a function, consider using @code{defalias} instead. @xref{Definition of defalias}. + +If the resulting function definition chain would be circular, then +Emacs will signal a @code{cyclic-function-indirection} error. @end defun @node Closures @@ -2023,9 +2027,16 @@ advice. Advice can also cause confusion in debugging, if the person doing the debugging does not notice or remember that the function has been modified by advice. - For these reasons, advice should be reserved for the cases where you -cannot modify a function's behavior in any other way. If it is -possible to do the same thing via a hook, that is preferable + Note that the problems are not due to advice per se, but to the act +of modifying a named function. It is even more problematic to modify +a named function via lower-level primitives like @code{fset}, +@code{defalias}, or @code{cl-letf}. From that point of view, advice +is the better way to modify a named function because it keeps track of +the modifications, so they can be listed and undone. + + Modifying a named function should be reserved for +the cases where you cannot modify Emacs' behavior in any other way. +If it is possible to do the same thing via a hook, that is preferable (@pxref{Hooks}). If you simply want to change what a particular key does, it may be better to write a new command, and remap the old command's key bindings to the new one (@pxref{Remapping Commands}). @@ -2054,9 +2065,10 @@ code) obey the advice and other calls (from C code) do not. @defmac define-advice symbol (where lambda-list &optional name depth) &rest body This macro defines a piece of advice and adds it to the function named -@var{symbol}. The advice is an anonymous function if @var{name} is -@code{nil} or a function named @code{symbol@@name}. See -@code{advice-add} for explanation of other arguments. +@var{symbol}. If @var{name} is non-nil, the advice is named +@code{@var{symbol}@@@var{name}} and installed with the name @var{name}; otherwise, +the advice is anonymous. See @code{advice-add} for explanation of +other arguments. @end defmac @defun advice-add symbol where function &optional props @@ -2065,10 +2077,12 @@ Add the advice @var{function} to the named function @var{symbol}. (@pxref{Core Advising Primitives}). @end defun -@defun advice-remove symbol function +@deffn Command advice-remove symbol function Remove the advice @var{function} from the named function @var{symbol}. -@var{function} can also be the @code{name} of a piece of advice. -@end defun +@var{function} can also be the @code{name} of a piece of advice. When +called interactively, prompt for both an advised @var{function} and +the advice to remove. +@end deffn @defun advice-member-p function symbol Return non-@code{nil} if the advice @var{function} is already in the named @@ -2206,7 +2220,7 @@ More specifically, the composition of the two functions behaves like: @findex defadvice @findex ad-activate -A lot of code uses the old @code{defadvice} mechanism, which is largely made +A lot of code uses the old @code{defadvice} mechanism, which has been made obsolete by the new @code{advice-add}, whose implementation and semantics is significantly simpler. @@ -2386,8 +2400,8 @@ accepted three arguments, like this (sit-for seconds milliseconds nodisp) @end example -However, calling @code{sit-for} this way is considered obsolete -(@pxref{Waiting}). The old calling convention is deprecated like +During a transition period, the function accepted those three +arguments, but declared this old calling convention as deprecated like this: @example @@ -2671,6 +2685,12 @@ so the byte compiler can ignore calls whose value is ignored. This is the same as the @code{side-effect-free} property of the function's symbol, @pxref{Standard Properties}. +@item (important-return-value @var{val}) +If @var{val} is non-@code{nil}, the byte compiler will warn about +calls to this function that do not use the returned value. This is the +same as the @code{important-return-value} property of the function's +symbol, @pxref{Standard Properties}. + @item (speed @var{n}) Specify the value of @code{native-comp-speed} in effect for native compilation of this function (@pxref{Native-Compilation Variables}). |