elisp: A Sample Function Description
1.3.7.1 A Sample Function Description
.....................................
In a function description, the name of the function being described
appears first. It is followed on the same line by a list of argument
names. These names are also used in the body of the description, to
stand for the values of the arguments.
The appearance of the keyword ‘&optional’ in the argument list
indicates that the subsequent arguments may be omitted (omitted
arguments default to ‘nil’). Do not write ‘&optional’ when you call the
function.
The keyword ‘&rest’ (which must be followed by a single argument
name) indicates that any number of arguments can follow. The single
argument name following ‘&rest’ receives, as its value, a list of all
the remaining arguments passed to the function. Do not write ‘&rest’
when you call the function.
Here is a description of an imaginary function ‘foo’:
-- Function: foo integer1 &optional integer2 &rest integers
The function ‘foo’ subtracts INTEGER1 from INTEGER2, then adds all
the rest of the arguments to the result. If INTEGER2 is not
supplied, then the number 19 is used by default.
(foo 1 5 3 9)
⇒ 16
(foo 5)
⇒ 14
More generally,
(foo W X Y...)
≡
(+ (- X W) Y...)
By convention, any argument whose name contains the name of a type
(e.g., INTEGER, INTEGER1 or BUFFER) is expected to be of that type. A
plural of a type (such as BUFFERS) often means a list of objects of that
type. An argument named OBJECT may be of any type. (For a list of
Emacs object types, 
Lisp Data Types.) An argument with any
other sort of name (e.g., NEW-FILE) is specific to the function; if the
function has a documentation string, the type of the argument should be
described there (Documentation).
Lambda Expressions, for a more complete description of
arguments modified by ‘&optional’ and ‘&rest’.
Command, macro, and special form descriptions have the same format,
but the word ‘Function’ is replaced by ‘Command’, ‘Macro’, or ‘Special
Form’, respectively. Commands are simply functions that may be called
interactively; macros process their arguments differently from functions
(the arguments are not evaluated), but are presented the same way.
The descriptions of macros and special forms use a more complex
notation to specify optional and repeated arguments, because they can
break the argument list down into separate arguments in more complicated
ways. ‘[OPTIONAL-ARG]’ means that OPTIONAL-ARG is optional and
‘REPEATED-ARGS...’ stands for zero or more arguments. Parentheses are
used when several arguments are grouped into additional levels of list
structure. Here is an example:
-- Special Form: count-loop (var [from to [inc]]) body...
This imaginary special form implements a loop that executes the
BODY forms and then increments the variable VAR on each iteration.
On the first iteration, the variable has the value FROM; on
subsequent iterations, it is incremented by one (or by INC if that
is given). The loop exits before executing BODY if VAR equals TO.
Here is an example:
(count-loop (i 0 10)
(prin1 i) (princ " ")
(prin1 (aref vector i))
(terpri))
If FROM and TO are omitted, VAR is bound to ‘nil’ before the loop
begins, and the loop exits if VAR is non-‘nil’ at the beginning of
an iteration. Here is an example:
(count-loop (done)
(if (pending)
(fixit)
(setq done t)))
In this special form, the arguments FROM and TO are optional, but
must both be present or both absent. If they are present, INC may
optionally be specified as well. These arguments are grouped with
the argument VAR into a list, to distinguish them from BODY, which
includes all remaining elements of the form.
Info Catalog
elisp: Format of Descriptions
elisp: A Sample Variable Description