Common Lisp the Language, 2nd Edition
Functions, variables, named constants, special forms, and macros are described using a distinctive typographical format. Table 1-1 illustrates the manner in which Common Lisp functions are documented. The first line specifies the name of the function, the manner in which it accepts arguments, and the fact that it is a function. If the function takes many arguments, then the names of the arguments may spill across two or three lines. The paragraphs following this standard header explain the definition and uses of the function and often present examples or related functions.
Sometimes two or more related functions are explained in a single combined description. In this situation the headers for all the functions appear together, followed by the combined description.
In general, actual code (including actual names of functions) appears in this typeface: (cons a b). Names that stand for pieces of code (metavariables) are written in italics. In a function description, the names of the parameters appear in italics for expository purposes. The word &optional in the list of parameters indicates that all arguments past that point are optional; the default values for the parameters are described in the text. Parameter lists may also contain &rest, indicating that an indefinite number of arguments may appear, or &key, indicating that keyword arguments are accepted. (The &optional/&rest/&key syntax is actually used in Common Lisp function definitions for these purposes.)
---------------------------------------------------------------- Table 1-1: Sample Function Description [Function] sample-function arg1 arg2 &optional arg3 arg4 The function sample-function adds together arg1 and arg2, and then multiplies the result by arg3. If arg3 is not provided or is nil, the multiplication isn't done. sample-function then returns a list whose first element is this result and whose section element is arg4 (which defaults to the symbol foo). For example: (sample-function 3 4) => (7 foo) (sample-function 1 2 2 'bar) => (6 bar) In general, (sample-function x y) == (list (+ x y) 'foo). ----------------------------------------------------------------
---------------------------------------------------------------- Table 1-2: Sample Variable Description [Variable] *sample-variable* The variable *sample-variable* specifies how many times the special form sample-special-form should iterate. The value should always be a non-negative integer or nil (which means iterate indefinitely many times). The initial value is 0 (meaning no iterations). ----------------------------------------------------------------
---------------------------------------------------------------- Table 1-3: Sample Constant Description [Constant] sample-constant The named constant sample-constant has as its value the height of the terminal screen in furlongs times the base-2 logarithm of the implementation's total disk capacity in bytes, as a floating-point number. ----------------------------------------------------------------
Table 1-2 illustrates the manner in which a global variable is documented. The first line specifies the name of the variable and the fact that it is a variable. Purely as a matter of convention, all global variables used by Common Lisp have names beginning and ending with an asterisk.
Table 1-3 illustrates the manner in which a named constant is documented. The first line specifies the name of the constant and the fact that it is a constant. (A constant is just like a global variable, except that it is an error ever to alter its value or to bind it to a new value.)
----------------------------------------------------------------
Table 1-4: Sample Special Form Description
[Special Form]
sample-special-form [name] ({var}*) {form}+
This evaluates each form in sequence as an implicit progn,
and does this as many times as specified by the global
variable *sample-variable*. Each variable var is
bound and initialized to 43 before the first iteration, and
unbound after the last iteration. The name name, if
supplied, may be used in a return-from form to exit from the
loop prematurely. If the loop ends normally,
sample-special-form returns nil. For example:
(setq *sample-variable* 3)
(sample-special-form () form1 form2)
This evaluates form1, form2, form1, form2, form1, form2,
in that order.
----------------------------------------------------------------
----------------------------------------------------------------
Table 1-5: Sample Macro Description
[Macro]
sample-macro var [[ declaration* | doc-string ]] {tag | statement}*
This evaluates the statements as a prog body, with the
variable var bound to 43.
(sample-macro x (return (+ x x))) => 86
(sample-macro var . body) -> (prog ((var 43)) . body)
----------------------------------------------------------------
Tables 1-4 and 1-5 illustrate the documentation of special forms and macros, which are closely related in purpose. These are very different from functions. Functions are called according to a single, specific, consistent syntax; the &optional/&rest/&key syntax specifies how the function uses its arguments internally but does not affect the syntax of a call. In contrast, each special form or macro can have its own idiosyncratic syntax. It is by special forms and macros that the syntax of Common Lisp is defined and extended.
In the description of a special form or macro, an italicized word names a corresponding part of the form that invokes the special form or macro. Parentheses stand for themselves and should be written as such when invoking the special form or macro. Brackets, braces, stars, plus signs, and vertical bars are metasyntactic marks. Brackets, [ and ], indicate that what they enclose is optional (may appear zero times or one time in that place); the square brackets should not be written in code. Braces, { and }, simply parenthesize what they enclose but may be followed by a star, *, or a plus sign, +; a star indicates that what the braces enclose may appear any number of times (including zero, that is, not at all), whereas a plus sign indicates that what the braces enclose may appear any non-zero number of times (that is, must appear at least once). Within braces or brackets, a vertical bar, |, separates mutually exclusive choices. In summary, the notation {x}* means zero or more occurrences of x, the notation {x}+ means one or more occurrences of x, and the notation [x] means zero or one occurrence of x. These notations are also used for syntactic descriptions expressed as BNF-like productions, as in table 22-2.
Double brackets, [[ and ]], indicate that any number of the
alternatives enclosed may be used, and those used
may occur in any order, but each
alternative may be used at most once unless followed by a star.
For example,
p [[x | {y}* | z]] q
means that
at most one x, any number of y's, and at most one z
may appear between the mandatory occurrences of p
and q, and those that appear may be in any order.
A downward arrow, 
, indicates a form of syntactic indirection
that helps to make
[[ ]] notation more readable. If X is
some non-terminal symbol occurring on the left-hand side of some BNF
production, then the right-hand
side of that production is to be textually substituted for any occurrence
of X. Thus the two fragments
p [[are together equivalent to the previous example.
).
In the last example in table 1-5, notice the use of dot notation. The dot appearing in the expression (sample-macro var . body) means that the name body stands for a list of forms, not just a single form, at the end of a list. This notation is often used in examples.
In the heading line in table 1-5, notice the
use of [[ ]] notation to indicate that any number of declarations
may appear but at most one documentation string (which may appear before,
after, or somewhere in the middle of any declarations).