[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r110550: More documentation fixes for
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r110550: More documentation fixes for changes to defun, defmacro, etc. |
Date: |
Mon, 15 Oct 2012 12:03:04 +0800 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110550
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2012-10-15 12:03:04 +0800
message:
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.
modified:
doc/lispref/ChangeLog
doc/lispref/functions.texi
doc/lispref/macros.texi
lisp/ChangeLog
lisp/emacs-lisp/byte-run.el
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-10-13 01:18:52 +0000
+++ b/doc/lispref/ChangeLog 2012-10-15 04:03:04 +0000
@@ -1,3 +1,14 @@
+2012-10-15 Chong Yidong <address@hidden>
+
+ * 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 <address@hidden>
* display.texi (ImageMagick Images): ImageMagick enabled by default.
=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi 2012-10-05 07:38:05 +0000
+++ b/doc/lispref/functions.texi 2012-10-15 04:03:04 +0000
@@ -522,21 +522,20 @@
is called @dfn{defining a function}, and it is done with the
@code{defun} special form.
address@hidden defun name argument-list body-forms...
address@hidden defun name args [doc] [declare] [interactive] address@hidden
@code{defun} is the usual way to define new Lisp functions. It
-defines the symbol @var{name} as a function that looks like this:
-
address@hidden
-(lambda @var{argument-list} . @var{body-forms})
address@hidden example
-
address@hidden stores this lambda expression in the function cell of
address@hidden 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}.
+defines the symbol @var{name} as a function with argument list
address@hidden and body forms given by @var{body}. Neither @var{name} nor
address@hidden should be quoted.
+
address@hidden, 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}).
+
+The return value of @code{defun} is undefined.
Here are some examples:
@@ -582,14 +581,14 @@
@end defmac
@cindex function aliases
address@hidden defalias name definition &optional docstring
address@hidden 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 address@hidden, it becomes the function
-documentation of @var{name}. Otherwise, any documentation provided by
+If @var{doc} is address@hidden, 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 @@
But typically you should use the @code{lambda} macro, or the
@code{function} special form, or the @code{#'} read syntax:
address@hidden 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
address@hidden forms ``self-quoting'': evaluating a form whose @sc{car}
-is @code{lambda} yields the form itself:
address@hidden lambda args [doc] [interactive] address@hidden
+This macro returns an anonymous function with argument list
address@hidden, documentation string @var{doc} (if any), interactive spec
address@hidden (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 @@
was first made obsolete---for example, a date or a release number.
@end defun
address@hidden define-obsolete-function-alias obsolete-name current-name
&optional when docstring
address@hidden 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 @@
@section Inline Functions
@cindex inline functions
address@hidden defsubst name argument-list body-forms...
-Define an inline function. The syntax is exactly the same as
address@hidden (@pxref{Defining Functions}).
address@hidden 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
address@hidden instead of @code{defun}.
+
address@hidden defsubst name args [doc] [declare] [interactive] address@hidden
+This macro defines an inline function. Its syntax is exactly the same
+as @code{defun} (@pxref{Defining Functions}).
address@hidden 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 @@
@anchor{Definition of declare}
@defmac declare @address@hidden
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
address@hidden 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
address@hidden 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
address@hidden
Each element in @var{specs} should have the form @code{(@var{property}
@address@hidden)}, which should not be quoted. These have the
=== modified file 'doc/lispref/macros.texi'
--- a/doc/lispref/macros.texi 2012-09-30 09:18:38 +0000
+++ b/doc/lispref/macros.texi 2012-10-15 04:03:04 +0000
@@ -185,35 +185,38 @@
@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
address@hidden 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.
address@hidden defmacro name argument-list address@hidden
address@hidden defines the symbol @var{name} as a macro that looks
-like this:
address@hidden defmacro name args [doc] [declare] address@hidden
address@hidden 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}.
+(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
address@hidden&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.
-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.
address@hidden defspec
address@hidden, if present, should be a string specifying the macro's
+documentation string. @var{declare}, if present, should be a
address@hidden form specifying metadata for the macro (@pxref{Declare
+Form}). Note that macros cannot have interactive declarations, since
+they cannot be called interactively.
address@hidden defmac
Macros often need to construct large list structures from a mixture
of constants and nonconstant parts. To make this easier, use the
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-10-14 17:07:00 +0000
+++ b/lisp/ChangeLog 2012-10-15 04:03:04 +0000
@@ -1,3 +1,7 @@
+2012-10-15 Chong Yidong <address@hidden>
+
+ * emacs-lisp/byte-run.el (defsubst): Doc fix.
+
2012-10-14 Eli Zaretskii <address@hidden>
* window.el (display-buffer): Doc fix.
=== modified file 'lisp/emacs-lisp/byte-run.el'
--- a/lisp/emacs-lisp/byte-run.el 2012-09-25 04:13:02 +0000
+++ b/lisp/emacs-lisp/byte-run.el 2012-10-15 04:03:04 +0000
@@ -232,7 +232,8 @@
;; 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))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r110550: More documentation fixes for changes to defun, defmacro, etc.,
Chong Yidong <=