From: Chong Yidong Date: Mon, 15 Oct 2012 04:03:04 +0000 (+0800) Subject: More documentation fixes for changes to defun, defmacro, etc. X-Git-Tag: emacs-24.2.90~233^2~15 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d18a0d2460cbcf73f9bd136912006fc0c11f55e0;p=emacs.git 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. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 40c457ffe07..acf6f8a51ff 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2012-10-15 Chong Yidong + + * 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 * display.texi (ImageMagick Images): ImageMagick enabled by default. diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 845561f91ec..c94e46dad18 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -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 diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 0a5152a43a1..8be6a3fbcde 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -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 diff --git a/lisp/ChangeLog b/lisp/ChangeLog index a14217358dc..96f859ec603 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,7 @@ +2012-10-15 Chong Yidong + + * emacs-lisp/byte-run.el (defsubst): Doc fix. + 2012-10-14 Eli Zaretskii * window.el (display-buffer): Doc fix. diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el index d740574f1e4..462b4a25154 100644 --- a/lisp/emacs-lisp/byte-run.el +++ b/lisp/emacs-lisp/byte-run.el @@ -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))