GNU Info

(elisp)A Sample Function Description

---

Next: A Sample Variable Description Up: Format of Descriptions

---

Enter node , (file) or (file)node

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
following argument name will have a value, as a variable, which is a
list of all these remaining arguments.  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...)

   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.
Arguments named OBJECT may be of any type.  (Note: Lisp Data Types,
for a list of Emacs object types.)  Arguments with other sorts of names
(e.g., NEW-FILE) are discussed specifically in the description of the
function.  In some sections, features common to the arguments of
several functions are described at the beginning.

   Note: Lambda Expressions, for a more complete description of
optional and rest arguments.

   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.

   Special form descriptions 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.