Descriptions

The simplest type of descriptions are the descriptions of variables (see section Variables), they look something like,

Variable: grains-of-sand

This imaginary variable contains the number of grains of sand in a one-mile long stretch of an averagely sandy beach.

Hooks (see section Hooks) are also described in this format, the only difference is that `Variable:' is replaced by `Hook:'.

Functions (see section Functions) and macros (see section Macros) have more complex descriptions; as well as the name of the thing being described, they also have a list of arguments which the thing will accept. Each argument in the list is named and may be referred to in the body of the description.

Two `special' arguments may be used, `&optional' and &rest. They have the same meaning as when used in the lambda-list of a function definition (see section Lambda Expressions), that is `&optional' means that all further arguments are optional, and `&rest' means that zero or more argument values are coalesced into a list to be used as the value of the following argument.

An example function definition follows.

Function: useless-function first &optional second &rest tail

This function returns a list consisting of the values second (when undefined the number 42 is used), all the items in the list tail and first.

(useless-function 'foo 'bar 'xyz 20)
    => (bar xyz 20 foo)

(useless-function '50)
    => (42 50)

Macros and commands (see section Commands) are defined in the same way with `Macro:' or `Command:' replacing `Function:'.

Special forms (see section Special Forms) are described similarly to functions except that the argument list is formatted differently since special forms are, by definition, more flexible in how they treat their arguments. Optional values are enclosed in square brackets (`[optional-arg]') and three dots (`repeated-arg...') indicate where zero or more arguments are allowed.

Go to the first, previous, next, last section, table of contents.