2Notation for Documentation

This chapter introduces essential terminology and notation that is
used throughout Racket documentation.

2.1Notation for Module Documentation

Since Racket programs are organized into modules, documentation
reflects that organization with an annotation at the beginning of a
section or subsection that describes the bindings that a particular
module provides.

For example, the section that describes the functionality provided by
racket/list starts

Using #lang means that the module is normally used as the
language of a whole module—that is, by a module that starts
#lang followed by the language—instead of imported with
require. Unless otherwise specified, however, a module name
documented with #lang can also be used with require to
obtain the language’s bindings.

Sometimes, a module specification appears at the beginning of a
document or at the start of a section that contains many subsections.
The document’s section or section’s subsections are meant to
“inherit” the module declaration of the enclosing document or
section. Thus, bindings documented in The Racket Reference are available from
racket and racket/base unless otherwise
specified in a section or subsection.

Since every form is expressed in terms of syntax
objects, parentheses in a grammar specification indicate a syntax
object wrapping a list, and the leading if is an identifier
that starts the list whose binding is the if binding
of the module being documented—in this case,
racket/base. Square brackets in the grammar indicate
a syntax-object list in the same way as parentheses, but in
places square brackets are normally used by convention in a program’s
source.

Italic identifiers in the grammar are metavariables
that correspond to other grammar productions. Certain metavariable
names have implicit grammar productions:

A metavariable that ends with expr stands for any
form, and the form will be parsed as an expression.

A metavariable that ends with body stands for any
form; the form will be parsed as either a local definition or
an expression. A body can parse as a definition only
if it is not preceded by any expression, and the last
body must be an expression; see also
Internal Definitions.

A metavariable that ends with datum stands for any
form, and the form is normally uninterpreted (e.g.,
quoted).

Finally, a grammar specification that includes expr
metavariables may be augmented with run-time contracts on some
of the metavariables, which indicate a predicate that the result of
the expression must satisfy at run time. For example,

The function being defined, char->integer, is typeset as if it
were being applied. The metavariables that come after the function name
stand in for arguments. The white text in the corner identifies the
kind of value that is being documented.

Each metavariable is described with a contract. In the preceding
example, the metavariable char has the contract
char?. This contract specifies that any argument
char that answers true to the char? predicate is
valid. The documented function may or may not actually check this
property, but the contract signals the intent of the implementer.

The contract on the right of the arrow, exact-integer? in this case,
specifies the expected result that is produced by the function.

Contract specifications can be more expressive than just names of
predicates. Consider the following header for argmax:

The contract (->any/creal?) denotes a function contract specifying
that proc’s argument can be any single value and the result should be
a real number. The contract (and/cpair?list?) for lst
specifies that lst should pass both pair? and list?
(i.e., that it is a non-empty list).

Both -> and and/c are examples of contract combinators.
Contract combinators such as or/c, cons/c, listof,
and others are used throughout the documentation. Clicking on the hyperlinked
combinator name will provide more information on its meaning.

A Racket function may be documented as having one or more optional arguments.
The read function is an example of such a function:

The brackets surrounding the in argument in the application
syntax indicates that it is an optional argument.

The header for read specifies a contract for the parameter
in as usual. To the right of the contract, it also specifies
a default value (current-input-port) that is used if
read is called with no arguments.

Functions may also be documented as accepting mandatory or optional
keyword-based arguments. For example, the sort function has
two optional, keyword-based arguments:

The brackets around the extract-key and
cache-keys? arguments indicate that they are optional as
before. The contract section of the header shows the default values
that are provided for these keyword arguments.

The structure type is typeset as it were declared in
the source code of a program using the struct form.
Each field of the structure is documented with a corresponding
contract that specifies the values that are accepted for that field.

In the example above, the structure type color has
four fields: red, green, blue,
and alpha. The constructor for the structure type
accepts field values that satisfy
(and/cnatural-number/c(<=/c255)), i.e., non-negative
exact integers up to 255.

Additional keywords may appear after the field names in the
documentation for a structure type: