4.3.3 Documenting Forms, Functions, Structure Types, and Values
| (defproc maybe-kind maybe-id prototype | | result-contract-expr-datum | | pre-flow ...) |
|
| |
| prototype | | = | | (id arg-spec ...) | | | | | | | (prototype arg-spec ...) | | | | | | | | arg-spec | | = | | (arg-id contract-expr-datum) | | | | | | | (arg-id contract-expr-datum default-expr) | | | | | | | (keyword arg-id contract-expr-datum) | | | | | | | (keyword arg-id contract-expr-datum default-expr) | | | | | | | ellipses | | | | | | | ellipses+ | | | | | | | | maybe-kind | | = | | | | | | | | | #:kind kind-string-expr | | | | | | | | maybe-id | | = | | | | | | | | | #:id [src-id dest-id-expr] | | | | | | | | ellipses | | = | | ... | | | | | | | | ellipses+ | | = | | ...+ |
|
Produces a sequence of flow elements (encapsulated in a
splice) to document a procedure named
id. Nesting
prototypes corresponds to a curried function, as in
define. The
id is indexed, and it also registered so
that
racket-typeset uses of the identifier (with the same
for-label binding) are hyperlinked to this documentation.
A defmodule or declare-exporting form (or one of the
variants) in an enclosing section determines the id binding
that is being defined. The id should also have a for-label
binding (as introduced by (require (for-label ....))) that
matches the definition binding; otherwise, the defined id
will not typeset correctly within the definition.
Each arg-spec must have one of the following forms:
| (arg-id contract-expr-datum) |
An argument whose contract is specified by
contract-expr-datum which is typeset via
racketblock0.
| (arg-id contract-expr-datum default-expr) |
Like the previous case, but with a default value. All arguments
with a default value must be grouped together, but they can be
in the middle of required arguments.
| (keyword arg-id contract-expr-datum) |
Like the first case, but for a keyword-based argument.
| (keyword arg-id contract-expr-datum default-expr) |
Like the previous case, but with a default
value.
Any number of the preceding argument. This
form is normally used at the end, but keyword-based arguments
can sensibly appear afterward. See also the documentation for
append for a use of ... before the last
argument.
One or more of the preceding argument
(normally at the end, like ...).
The result-contract-expr-datum is typeset via
racketblock0, and it represents a contract on the procedure’s
result.
The decoded pre-flow documents the procedure. In this
description, references to arg-ids using racket,
racketblock, etc. are typeset as procedure arguments.
The typesetting of all information before the pre-flows
ignores the source layout, except that the local formatting is
preserved for contracts and default-values expressions. The information
is formatted to fit (if possible) in the number of characters specified
by the current-display-width parameter.
An optional #:kind specification chooses the decorative
label, which defaults to "procedure". A #f
result for kind-string-expr uses the default, otherwise
kind-string-expr should produce a string. An alternate
label should be all lowercase.
If #:id [src-id dest-id-expr] is supplied, then
src-id is the identifier as it appears in the
prototype (to be replaced by a defining instance), and
dest-id-expr produces the identifier to be documented in
place of src-id. This split between src-id and
dest-id-expr roles is useful for functional abstraction of
defproc.
Examples:
| @defproc[(make-sandwich [ingredients (listof ingredient?)]) |
| sandwich?]{ |
| Returns a sandwich given the right ingredients. |
| } |
| |
| @defproc[#:kind "sandwich-maker" |
| (make-reuben [ingredient sauerkraut?] ... |
| [#:veggie? veggie? any/c #f]) |
| sandwich?]{ |
| Produces a reuben given some number of @racket[ingredient]s. |
| |
| If @racket[veggie?] is @racket[#f], produces a standard |
| reuben with corned beef. Otherwise, produces a vegetable |
| reuben. |
| } |
| (defproc* maybe-kind maybe-id | | ([prototype | | result-contract-expr-datum] ...) | | pre-flow ...) |
|
Like
defproc, but for multiple cases with the same
id.
When an id has multiple calling cases, they must be defined
with a single defproc*, so that a single definition point
exists for the id. However, multiple distinct ids
can also be defined by a single defproc*, for the case that
it’s best to document a related group of procedures at once.
Examples:
| @defproc[((make-pb&j) |
| (make-pb&j [jelly jelly?])) |
| sandwich?]{ |
| Returns a peanut butter and jelly sandwich. If @racket[jelly] |
| is provided, then it is used instead of the standard (grape) |
| jelly. |
| } |
| (defform maybe-kind maybe-id maybe-literals form-datum | | maybe-grammar maybe-contracts | | pre-flow ...) |
|
| |
| maybe-kind | | = | | | | | | | | | #:kind kind-string-expr | | | | | | | | maybe-id | | = | | | | | | | | | #:id id | | | | | | | #:id [id id-expr] | | | | | | | | maybe-literals | | = | | | | | | | | | #:literals (literal-id ...) | | | | | | | | maybe-grammar | | = | | | | | | | | | #:grammar ([nonterm-id clause-datum ...+] ...) | | | | | | | | maybe-contracts | | = | | | | | | | | | | #:contracts ([subform-datum contract-expr-datum] | | ...) |
|
|
Produces a sequence of flow elements (encapsulated in a
splice) to document a syntatic form named by
id (or the
result of
id-expr) whose syntax is described by
form-datum. If no
#:id is used to specify
id, then
form-datum must have the form
(id . datum).
If #:kind kind-string-expr is supplied, it is used in the
same way as for defproc, but the default kind is
"syntax".
If #:id [id id-expr] is supplied, then id is the
identifier as it appears in the form-datum (to be replaced by
a defining instance), and id-expr produces the identifier to
be documented. This split between id and id-expr
roles is useful for functional abstraction of defform.
The id (or result of id-expr) is indexed, and it is
also registered so that racket-typeset uses of the identifier
(with the same for-label binding) are hyperlinked to this
documentation. The defmodule or declare-exporting
requirements, as well as the binding requirements for id (or
result of id-expr), are the same as for defproc.
The decoded pre-flow documents the form. In this
description, a reference to any identifier in form-datum via
racket, racketblock, etc. is typeset as a sub-form
non-terminal. If #:literals clause is provided, however,
instances of the literal-ids are typeset normally (i.e., as
determined by the enclosing context).
If a #:grammar clause is provided, it includes an auxiliary
grammar of non-terminals shown with the id form. Each
nonterm-id is specified as being any of the corresponding
clause-datums.
If a #:contracts clause is provided, each
subform-datum (typically an identifier that serves as a
meta-variable in form-datum or clause-datum) is
shown as producing a value that must satisfy the contract described by
contract-expr-datum. Use #:contracts only to
specify constraints on a value produced by an expression; for
constraints on the syntax of a subform-datum, use
grammar notation instead, possibly through an auxiliary grammar
specified with #:grammar.
The typesetting of form-datum, clause-datum,
subform-datum, and contract-expr-datum preserves the
source layout, like racketblock.
Examples:
| @defform[(sandwich-promise sandwich-expr) |
| #:contracts ([sandwich-expr sandwich?])]{ |
| Returns a promise to construct a sandwich. When forced, the promise |
| will produce the result of @racket[sandwich-expr]. |
| } |
| |
| @defform[#:literals (sandwich mixins) |
| (sandwich-promise* [sandwich sandwich-expr] |
| [mixins ingredient-expr ...]) |
| #:contracts ([sandwich-expr sandwich?] |
| [ingreient-expr ingredient?])]{ |
| Returns a promise to construct a sandwich. When forced, the promise |
| will produce the result of @racket[sandwich-expr]. Each result of |
| the @racket[ingredient-expr]s will be mixed into the resulting |
| sandwich. |
| } |
| |
| @defform[(sandwich-factory maybe-name factory-component ...) |
| #:grammar |
| [(maybe-name (code:line) |
| name) |
| (factory-component (code:line #:protein protein-expr) |
| [vegetable vegetable-expr])]]{ |
| Constructs a sandwich factory. If @racket[maybe-name] is provided, |
| the factory will be named. Each of the @racket[factory-component] |
| clauses adds an additional ingredient to the sandwich pipeline. |
| } |
| (defform* maybe-kind maybe-id maybe-literals [form-datum ...+] | | maybe-grammar maybe-contracts | | pre-flow ...) |
|
Like
defform, but for multiple forms using the same
id.
Examples:
| @defform*[((call-with-current-sandwich expr) |
| (call-with-current-sandwich expr sandwich-handler-expr))]{ |
| Runs @racket[expr] and passes it the value of the current |
| sandwich. If @racket[sandwich-handler-expr] is provided, its result |
| is invoked when the current sandwich is eaten. |
| } |
| (defform/none maybe-kind maybe-literal form-datum | | maybe-grammar maybe-contracts | | pre-flow ...) |
|
Like
defform, but without registering a definition.
Like
defform, but with a plain
id as the form.
Like
defidform, but
id (or the result of
id-expr, analogous to
defform) is typeset as an
inline element. Use this form sparingly, because the typeset form does
not stand out to the reader as a specification of
id.
| (specform maybe-literals datum maybe-grammar maybe-contracts | | pre-flow ...) |
|
Like
defform, but without indexing or registering a
definition, and with indenting on the left for both the specification
and the
pre-flows.
| (specsubform maybe-literals datum maybe-grammar maybe-contracts | | pre-flow ...) |
|
Similar to
defform, but without any specific identifier being
defined, and the table and flow are typeset indented. This form is
intended for use when refining the syntax of a non-terminal used in a
defform or other
specsubform. For example, it is
used in the documentation for
defproc in the itemization of
possible shapes for
arg-spec.
The pre-flows list is parsed as a flow that documents the
procedure. In this description, a reference to any identifier in
datum is typeset as a sub-form non-terminal.
| (specspecsubform maybe-literals datum maybe-grammar maybe-contracts | | pre-flow ...) |
|
| (defform/subs maybe-kind maybe-id maybe-literals form-datum | | ([nonterm-id clause-datum ...+] ...) | | maybe-contracts | | pre-flow ...) |
|
|
| (defform*/subs maybe-kind maybe-id maybe-literals [form-datum ...+] | | ([nonterm-id clause-datum ...+] ...) | | maybe-contracts | | pre-flow ...) |
|
|
| (specform/subs maybe-literals datum | | ([nonterm-id clause-datum ...+] ...) | | maybe-contracts | | pre-flow ...) |
|
|
| (specsubform/subs maybe-literals datum | | ([nonterm-id clause-datum ...+] ...) | | maybe-contracts | | pre-flow ...) |
|
|
| (specspecsubform/subs maybe-literals datum | | ([nonterm-id clause-datum ...+] ...) | | maybe-contracts | | pre-flow ...) |
|
|
Examples:
| @defform/subs[(sandwich-factory maybe-name factory-component ...) |
| [(maybe-name (code:line) |
| name) |
| (factory-component (code:line #:protein protein-expr) |
| [vegetable vegetable-expr])]]{ |
| Constructs a sandwich factory. If @racket[maybe-name] is provided, |
| the factory will be named. Each of the @racket[factory-component] |
| clauses adds an additional ingredient to the sandwich pipeline. |
| } |
(defparam id arg-id contract-expr-datum pre-flow ...)
|
Like
defproc, but for a parameter. The
contract-expr-datum serves as both the result contract on the
parameter and the contract on values supplied for the parameter. The
arg-id refers to the parameter argument in the latter case.
Examples:
| @defparam[current-sandwich sandwich sandwich?]{ |
| A parameter that defines the current sandwich for operations that |
| involve eating a sandwich. |
| } |
Like
defparam, but the contract on a parameter argument is
any/c, and the contract on the parameter result is
boolean?.
| (defthing maybe-kind maybe-id id contract-expr-datum | | pre-flow ...) |
|
| |
| maybe-kind | | = | | | | | | | | | #:kind kind-string-expr | | | | | | | | maybe-id | | = | | | | | | | | | #:id id-expr |
|
Like
defproc, but for a non-procedure binding.
If #:kind kind-string-expr is supplied,
it is used in the same way as for
defproc, but the default kind is "value".
If #:id id-expr is supplied, then the result of
id-expr is used in place of id.
Examples:
| @defthing[moldy-sandwich sandwich?]{ |
| Don't eat this. Provided for backwards compatibility. |
| } |
| (defstruct* struct-name ([field-name contract-expr-datum] ...) | | maybe-mutable maybe-non-opaque maybe-constructor | | pre-flow ...) |
|
|
| (defstruct struct-name ([field-name contract-expr-datum] ...) | | maybe-mutable maybe-non-opaque maybe-constructor | | pre-flow ...) |
| | | | struct-name | | = | | id | | | | | | | (id super-id) | | | | | | | | maybe-mutable | | = | | | | | | | | | #:mutable | | | | | | | | maybe-non-opaque | | = | | | | | | | | | #:prefab | | | | | | | #:transparent | | | | | | | | maybe-constructor | | = | | | | | | | | | #:constructor-name constructor-id | | | | | | | #:extra-constructor-name constructor-id |
|
|
Examples:
| @defstruct[sandwich ([protein ingredient?] [sauce ingredient?])]{ |
| A strucure type for sandwiches. Sandwiches are a pan-human foodstuff |
| composed of a partially-enclosing bread material and various |
| ingredients. |
| } |
Combines the definitions created by the
def-exprs into a
single definition box. Each
def-expr should produce a
definition point via
defproc,
defform, etc. Each
def-expr should have an empty
pre-flow; the
decoded
pre-flow sequence for the
deftogether
form documents the collected bindings.
Examples:
| @deftogether[(@defthing[test-sandwich-1 sandwich?] |
| @defthing[test-sandwich-2 sandwich?])]{ |
| Two high-quality sandwiches. These are provided for convenience |
| in writing test cases |
| } |
(racketgrammar maybe-literals id clause-datum ...+)
|
| |
| maybe-literals | | = | | | | | | | | | #:literals (literal-id ...) |
|
Creates a table to define the grammar of
id. Each identifier
mentioned in a
clause-datum is typeset as a non-terminal,
except for the identifiers listed as
literal-ids, which are
typeset as with
racket.
Like
racketgrammar, but for typesetting multiple productions
at once, aligned around the
= and
|.
Typesets
id as a Racket identifier, and also establishes the
identifier as the definition of a binding in the same way as
defproc,
defform, etc. As always, the library that
provides the identifier must be declared via
defmodule or
declare-exporting for an enclosing section.
If form? is a true value, then the identifier is documented
as a syntactic form, so that uses of the identifier (normally
including id itself) are typeset as a syntactic form.
If index? is a true value, then the identifier is registered
in the index.
If show-libs? is a true value, then the identifier’s defining
module may be exposed in the typeset form (e.g., when viewing HTML and
the mouse hovers over the identifier).
Specifies the target maximum width in characters for the output of
defproc and
defstruct.