(lispref.info)A Sample Function Description

Next: A Sample Variable Description Prev: Format of Descriptions Up: Format of Descriptions

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 parameters.
The names used for the parameters are also used in the body of the

   The appearance of the keyword `&optional' in the parameter list
indicates that the arguments for subsequent parameters may be omitted
(omitted parameters default to `nil').  Do not write `&optional' when
you call the function.

   The keyword `&rest' (which will always be followed by a single
parameter) indicates that any number of arguments can follow.  The value
of the single following parameter will be a list of all these 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 parameter 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.
Parameters named OBJECT may be of any type.  (Note: Types of Lisp
Object, for a list of Emacs object types.) Parameters with other
sorts of names (e.g., NEW-FILE) are discussed specifically in the
description of the function.  In some sections, features common to
parameters 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 parameters 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 1 (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, then 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)
              (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.

automatically generated by info2www