Commit d18a0d24 authored by Chong Yidong's avatar Chong Yidong

More documentation fixes for changes to defun, defmacro, etc.

* doc/lispref/functions.texi (Anonymous Functions): Explicitly list the
docstring, declare, and interactive arguments to lambda.
(Defining Functions): Likewise for defun.
(Inline Functions): Likewise for defsubst.
(Declare Form): Tweak description.

* doc/lispref/macros.texi (Defining Macros):  defmacro is now a macro.
Explicitly list the docstring and declare arguments.

* emacs-lisp/byte-run.el (defsubst): Doc fix.
parent 3e0341b0
2012-10-15 Chong Yidong <cyd@gnu.org>
* macros.texi (Defining Macros): defmacro is now a macro.
Explicitly list the docstring and declare arguments.
* functions.texi (Anonymous Functions): Explicitly list the
docstring, declare, and interactive arguments to lambda.
(Defining Functions): Likewise for defun.
(Inline Functions): Likewise for defsubst.
(Declare Form): Tweak description.
2012-10-13 Chong Yidong <cyd@gnu.org>
* display.texi (ImageMagick Images): ImageMagick enabled by default.
......
......@@ -522,21 +522,20 @@ Scheme.)
is called @dfn{defining a function}, and it is done with the
@code{defun} special form.
@defmac defun name argument-list body-forms...
@defmac defun name args [doc] [declare] [interactive] body@dots{}
@code{defun} is the usual way to define new Lisp functions. It
defines the symbol @var{name} as a function that looks like this:
defines the symbol @var{name} as a function with argument list
@var{args} and body forms given by @var{body}. Neither @var{name} nor
@var{args} should be quoted.
@example
(lambda @var{argument-list} . @var{body-forms})
@end example
@var{doc}, if present, should be a string specifying the function's
documentation string (@pxref{Function Documentation}). @var{declare},
if present, should be a @code{declare} form specifying function
metadata (@pxref{Declare Form}). @var{interactive}, if present,
should be an @code{interactive} form specifying how the function is to
be called interactively (@pxref{Interactive Call}).
@code{defun} stores this lambda expression in the function cell of
@var{name}. Its return value is @emph{undefined}.
As described previously, @var{argument-list} is a list of argument
names and may include the keywords @code{&optional} and @code{&rest}.
Also, the first two of the @var{body-forms} may be a documentation
string and an interactive declaration. @xref{Lambda Components}.
The return value of @code{defun} is undefined.
Here are some examples:
......@@ -582,14 +581,14 @@ redefinition from unintentional redefinition.
@end defmac
@cindex function aliases
@defun defalias name definition &optional docstring
@defun defalias name definition &optional doc
@anchor{Definition of defalias}
This special form defines the symbol @var{name} as a function, with
definition @var{definition} (which can be any valid Lisp function).
Its return value is @emph{undefined}.
If @var{docstring} is non-@code{nil}, it becomes the function
documentation of @var{name}. Otherwise, any documentation provided by
If @var{doc} is non-@code{nil}, it becomes the function documentation
of @var{name}. Otherwise, any documentation provided by
@var{definition} is used.
The proper place to use @code{defalias} is where a specific function
......@@ -902,11 +901,14 @@ function, you can in principle use any method to construct the list.
But typically you should use the @code{lambda} macro, or the
@code{function} special form, or the @code{#'} read syntax:
@defmac lambda args body...
This macro returns an anonymous function with argument list @var{args}
and body forms given by @var{body}. In effect, this macro makes
@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
is @code{lambda} yields the form itself:
@defmac lambda args [doc] [interactive] body@dots{}
This macro returns an anonymous function with argument list
@var{args}, documentation string @var{doc} (if any), interactive spec
@var{interactive} (if any), and body forms given by @var{body}.
In effect, this macro makes @code{lambda} forms ``self-quoting'':
evaluating a form whose @sc{car} is @code{lambda} yields the form
itself:
@example
(lambda (x) (* x x))
......@@ -1169,13 +1171,13 @@ If provided, @var{when} should be a string indicating when the function
was first made obsolete---for example, a date or a release number.
@end defun
@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc
This convenience macro marks the function @var{obsolete-name} obsolete
and also defines it as an alias for the function @var{current-name}.
It is equivalent to the following:
@example
(defalias @var{obsolete-name} @var{current-name} @var{docstring})
(defalias @var{obsolete-name} @var{current-name} @var{doc})
(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
@end example
@end defmac
......@@ -1213,16 +1215,16 @@ this:
@section Inline Functions
@cindex inline functions
@defmac defsubst name argument-list body-forms...
Define an inline function. The syntax is exactly the same as
@code{defun} (@pxref{Defining Functions}).
@end defmac
You can define an @dfn{inline function} by using @code{defsubst}
instead of @code{defun}. An inline function works just like an
ordinary function except for one thing: when you byte-compile a call
An @dfn{inline function} is a function that works just like an
ordinary function, except for one thing: when you byte-compile a call
to the function (@pxref{Byte Compilation}), the function's definition
is expanded into the caller.
is expanded into the caller. To define an inline function, use
@code{defsubst} instead of @code{defun}.
@defmac defsubst name args [doc] [declare] [interactive] body@dots{}
This macro defines an inline function. Its syntax is exactly the same
as @code{defun} (@pxref{Defining Functions}).
@end defmac
Making a function inline often makes its function calls run faster.
But it also has disadvantages. For one thing, it reduces flexibility;
......@@ -1266,16 +1268,13 @@ convention in Emacs Lisp mode.
@anchor{Definition of declare}
@defmac declare @var{specs}@dots{}
This macro ignores its arguments and evaluates to @code{nil}; it has
no run-time effect. However, when a @code{declare} form occurs as the
@emph{very first form} in the body of a @code{defun} function
definition or a @code{defmacro} macro definition (@pxref{Defining
Macros}, for a description of @code{defmacro}), it appends the
properties specified by @var{specs} to the function or macro. This
work is specially performed by the @code{defun} and @code{defmacro}
macros.
Note that if you put a @code{declare} form in an interactive function,
it should go before the @code{interactive} form.
no run-time effect. However, when a @code{declare} form occurs in the
@var{declare} argument of a @code{defun} or @code{defsubst} function
definition (@pxref{Defining Functions}) or a @code{defmacro} macro
definition (@pxref{Defining Macros}), it appends the properties
specified by @var{specs} to the function or macro. This work is
specially performed by @code{defun}, @code{defsubst}, and
@code{defmacro}.
Each element in @var{specs} should have the form @code{(@var{property}
@var{args}@dots{})}, which should not be quoted. These have the
......
......@@ -185,35 +185,38 @@ During Compile}).
@node Defining Macros
@section Defining Macros
A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should
be a function; expansion of the macro works by applying the function
(with @code{apply}) to the list of unevaluated argument-expressions
from the macro call.
A Lisp macro object is a list whose @sc{car} is @code{macro}, and
whose @sc{cdr} is a lambda expression. Expansion of the macro works
by applying the lambda expression (with @code{apply}) to the list of
@emph{unevaluated} arguments from the macro call.
It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
an anonymous macro to functionals such as @code{mapcar}. In practice,
all Lisp macros have names, and they are usually defined with the
special form @code{defmacro}.
function, but this is never done, because it does not make sense to
pass an anonymous macro to functionals such as @code{mapcar}. In
practice, all Lisp macros have names, and they are almost always
defined with the @code{defmacro} macro.
@defspec defmacro name argument-list body-forms@dots{}
@code{defmacro} defines the symbol @var{name} as a macro that looks
like this:
@defmac defmacro name args [doc] [declare] body@dots{}
@code{defmacro} defines the symbol @var{name} (which should not be
quoted) as a macro that looks like this:
@example
(macro lambda @var{argument-list} . @var{body-forms})
(macro lambda @var{args} . @var{body})
@end example
(Note that the @sc{cdr} of this list is a function---a lambda expression.)
This macro object is stored in the function cell of @var{name}. Its return
value is @emph{undefined}.
The shape and meaning of @var{argument-list} is the same as in a
function, and the keywords @code{&rest} and @code{&optional} may be used
(@pxref{Argument List}). Macros may have a documentation string, but
any @code{interactive} declaration is ignored since macros cannot be
called interactively.
@end defspec
(Note that the @sc{cdr} of this list is a lambda expression.) This
macro object is stored in the function cell of @var{name}. The
meaning of @var{args} is the same as in a function, and the keywords
@code{&rest} and @code{&optional} may be used (@pxref{Argument List}).
Neither @var{name} nor @var{args} should be quoted. The return value
of @code{defmacro} is undefined.
@var{doc}, if present, should be a string specifying the macro's
documentation string. @var{declare}, if present, should be a
@code{declare} form specifying metadata for the macro (@pxref{Declare
Form}). Note that macros cannot have interactive declarations, since
they cannot be called interactively.
@end defmac
Macros often need to construct large list structures from a mixture
of constants and nonconstant parts. To make this easier, use the
......
2012-10-15 Chong Yidong <cyd@gnu.org>
* emacs-lisp/byte-run.el (defsubst): Doc fix.
2012-10-14 Eli Zaretskii <eliz@gnu.org>
* window.el (display-buffer): Doc fix.
......
......@@ -232,7 +232,8 @@ The return value is undefined.
;; fns)))
(defmacro defsubst (name arglist &rest body)
"Define an inline function. The syntax is just like that of `defun'."
"Define an inline function. The syntax is just like that of `defun'.
\(fn NAME ARGLIST &optional DOCSTRING DECL &rest BODY)"
(declare (debug defun) (doc-string 3))
(or (memq (get name 'byte-optimizer)
'(nil byte-compile-inline-expand))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment