A @dfn{macro} is a construct defined in Lisp by the programmer. It
differs from a function in that it translates a Lisp expression that you
write into an equivalent expression to be evaluated instead of the
-original expression. @xref{Macros}, for how to define and use macros.
+original expression. Macros enable Lisp programmers to do the sorts of
+things that special forms can do. @xref{Macros}, for how to define and
+use macros.
@item command
@cindex command
@end example
@noindent
-(Such a list is called a @dfn{lambda expression} for historical reasons,
-even though it is not really an expression at all---it is not a form
-that can be evaluated meaningfully.)
+Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
+actually is valid as an expression---it evaluates to itself. In some
+other Lisp dialects, a lambda expression is not a valid expression at
+all. In either case, its main use is not to be evaluated as an
+expression, but to be called as a function.
@menu
* Lambda Components:: The parts of a lambda expression.
facilities. @xref{Documentation}, for how the @var{documentation-string} is
accessed.
- It is a good idea to provide documentation strings for all commands,
-and for all other functions in your program that users of your program
-should know about; internal functions might as well have only comments,
-since comments don't take up any room when your program is loaded.
+ It is a good idea to provide documentation strings for all the
+functions in your program, even those that are only called from within
+your program. Documentation strings are like comments, except that they
+are easier to access.
The first line of the documentation string should stand on its own,
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, but since
-these spaces come before the starting double-quote, they are not part of
+ 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{This is a mistake.} The indentation of the following lines is
@defun defalias name definition
This special form defines the symbol @var{name} as a function, with
definition @var{definition} (which can be any valid Lisp function).
-It's best to use this rather than @code{fset} when defining a function
-in a file, because @code{defalias} records which file defined the
-function (@pxref{Unloading}), while @code{fset} does not.
+
+The proper place to use @code{defalias} is where a specific function
+name is being defined---especially where that name appears explicitly in
+the source file being loaded. This is because @code{defalias} records
+which file defined the function, just like @code{defun}
+(@pxref{Unloading}).
+
+By contrast, in programs that manipulate function definitions for other
+purposes, it is better to use @code{fset}, which does not keep such
+records.
@end defun
+ See also @code{defsubst}, which defines a function like @code{defun}
+and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
+
@node Calling Functions
@section Calling Functions
@cindex function invocation
lists) and call them using @code{funcall} or @code{apply}. Functions
that accept function arguments are often called @dfn{functionals}.
- Sometimes, when you call such a function, it is useful to supply a
-no-op function as the argument. Here are two different kinds of no-op
+ Sometimes, when you call a functional, it is useful to supply a no-op
+function as the argument. Here are two different kinds of no-op
function:
@defun identity arg
@end example
@end defun
-@defun fset symbol object
-This function stores @var{object} in the function cell of @var{symbol}.
-The result is @var{object}. Normally @var{object} should be a function
+@defun fset symbol definition
+This function stores @var{definition} in the function cell of @var{symbol}.
+The result is @var{definition}. Normally @var{definition} should be a function
or the name of a function, but this is not checked.
There are three normal uses of this function:
@end defun
When writing a function that extends a previously defined function,
-the following idiom is often used:
+the following idiom is sometimes used:
@example
(fset 'old-foo (symbol-function 'foo))
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.
+
@node Inline Functions
@section Inline Functions
@cindex inline functions
Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.
-Emacs versions prior to 19 did not have inline functions.
+@c Emacs versions prior to 19 did not have inline functions.
@node Related Topics
@section Other Topics Related to Functions