# HG changeset patch # User Richard M. Stallman # Date 1108375908 0 # Node ID 88341b374ad001eee189ebd4333104dfcce73e97 # Parent 45e78cd94f23d6a08d021d51fd04f02aeaf94637 (What Is a Function): Wording cleanup. (Function Documentation): Minor cleanup. Explain purpose of calling convention at end of doc string. (Function Names): Wording cleanup. (Calling Functions): Wording cleanup. Explain better how funcall calls the function. (Function Cells): Delete example of saving and redefining function. diff -r 45e78cd94f23 -r 88341b374ad0 lispref/functions.texi --- a/lispref/functions.texi Mon Feb 14 10:07:43 2005 +0000 +++ b/lispref/functions.texi Mon Feb 14 10:11:48 2005 +0000 @@ -53,7 +53,7 @@ @cindex built-in function A @dfn{primitive} is a function callable from Lisp that is written in C, such as @code{car} or @code{append}. These functions are also called -@dfn{built-in} functions or @dfn{subrs}. (Special forms are also +@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also considered primitives.) Usually the reason we implement a function as a primitive is either @@ -412,13 +412,14 @@ because @code{apropos} displays just this first line. It should consist of one or two complete sentences that summarize the function's purpose. - The start of the documentation string is usually indented in the source file, -but since these spaces come before the starting double-quote, they are not part of -the string. Some people make a practice of indenting any additional -lines of the string so that the text lines up in the program source. -@emph{That is a mistake.} The 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. + The start of the documentation string is usually indented in the +source file, but since these spaces come before the starting +double-quote, they are not part of the string. Some people make a +practice of indenting any additional lines of the string so that the +text lines up in the program source. @emph{That is a mistake.} The +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). @@ -438,9 +439,14 @@ @noindent following a blank line, at the beginning of the line, with no newline -following it inside the documentation string. This feature is -particularly useful for macro definitions. The @samp{\} is used to -avoid confusing the Emacs motion commands. +following it inside the documentation string. (The @samp{\} is used +to avoid confusing the Emacs motion commands.) The calling convention +specified in this way appears in help messages in place of the one +derived from the actual arguments of the function. + + This feature is particularly useful for macro definitions, since the +arguments written in a macro definition often do not correspond to the +way users think of the parts of the macro call. @node Function Names @section Naming a Function @@ -481,8 +487,8 @@ We often identify functions with the symbols used to name them. For example, we often speak of ``the function @code{car}'', not distinguishing between the symbol @code{car} and the primitive -subr-object that is its function definition. For most purposes, there -is no need to distinguish. +subr-object that is its function definition. For most purposes, the +distinction is not important. Even so, keep in mind that a function need not have a unique name. While a given function object @emph{usually} appears in the function cell of only @@ -626,13 +632,12 @@ function @code{concat} with arguments @code{"a"} and @code{"b"}. @xref{Evaluation}, for a description of evaluation. - When you write a list as an expression in your program, the function -name it calls is written in your program. This means that you choose -which function to call, and how many arguments to give it, when you -write the program. Usually that's just what you want. Occasionally you -need to compute at run time which function to call. To do that, use the -function @code{funcall}. When you also need to determine at run time -how many arguments to pass, use @code{apply}. + When you write a list as an expression in your program, you specify +which function to call, and how many arguments to give it, in the text +of the program. Usually that's just what you want. Occasionally you +need to compute at run time which function to call. To do that, use +the function @code{funcall}. When you also need to determine at run +time how many arguments to pass, use @code{apply}. @defun funcall function &rest arguments @code{funcall} calls @var{function} with @var{arguments}, and returns @@ -641,11 +646,12 @@ Since @code{funcall} is a function, all of its arguments, including @var{function}, are evaluated before @code{funcall} is called. This means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the expressions -you write for the @var{arguments}, only their values. These values are -@emph{not} evaluated a second time in the act of calling @var{function}; -@code{funcall} enters the normal procedure for calling a function at the -place where the arguments have already been evaluated. +called. It also means that @code{funcall} does not see the +expressions you write for the @var{arguments}, only their values. +These values are @emph{not} evaluated a second time in the act of +calling @var{function}; the operation of @code{funcall} is like the +normal procedure for calling a function, once its arguments have +already been evaluated. The argument @var{function} must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because @@ -1137,30 +1143,12 @@ @end example @end defun - When writing a function that extends a previously defined function, -the following idiom is sometimes used: - -@example -(fset 'old-foo (symbol-function 'foo)) -(defun foo () - "Just like old-foo, except more so." -@group - (old-foo) - (more-so)) -@end group -@end example - -@noindent -This does not work properly if @code{foo} has been defined to autoload. -In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts -to define @code{old-foo} by loading a file. Since this presumably -defines @code{foo} rather than @code{old-foo}, it does not produce the -proper results. The only way to avoid this problem is to make sure the -file is loaded before moving aside the old definition of @code{foo}. - - But it is unmodular and unclean, in any case, for a Lisp file to -redefine a function defined elsewhere. It is cleaner to use the advice -facility (@pxref{Advising Functions}). + @code{fset} is sometimes used to save the old definition of a +function before redefining it. That permits the new definition to +invoke the old definition. But it is unmodular and unclean for a Lisp +file to redefine a function defined elsewhere. If you want to modify +a function defined by another package, it is cleaner to use +@code{defadvice} (@pxref{Advising Functions}). @node Inline Functions @section Inline Functions