In this document the simplest type of descriptions are those defining variables (see Variables), they look something like:
This imaginary variable contains the number of grains of sand in a one-mile long stretch of an averagely sandy beach.
Hooks (see Hooks) are also described in this format, the only difference is that ‘Variable:’ is replaced by ‘Hook:’.
Functions (see Functions) and macros (see Macros) have more complex descriptions; as well as the name of the object being described, they also have a list of parameters which the object will accept. Each parameter in the list is named and may be referred to in the body of the description.
Three keyword parameters may also be used:
#!rest. They have the same meaning as when used
in the lambda-list of a function definition (see Lambda Expressions). That is,
#!optional means that all further
parameters are optional, and
#!rest means that the following
parameter actually receives a list of any unused argument values.
An example function definition follows.
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 interactive commands are defined in the same way with ‘Macro:’ or ‘Command:’ replacing ‘Function:’.
Special forms (see 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.