4.2.3 Documenting Forms, Functions, Structure Types, and Values

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

▼ | 4.2 | Manual Forms

4.2.1 | Typesetting Code
4.2.2 | Documenting Modules
4.2.3 | Documenting Forms, Functions, Structure Types, and Values
4.2.4 | Documenting Classes and Interfaces
4.2.5 | Documenting Signatures
4.2.6 | Various String Forms
4.2.7 | Links
4.2.8 | Indexing
4.2.9 | Bibliography
4.2.10 | Version History
4.2.11 | Miscellaneous
4.2.12 | Index-Entry Descriptions
4.2.13 | Manual Rendering Style

On this page:

defproc
defproc*
defform
defform*
defform/ none
defidform
defidform/ inline
defsubform
defsubform*
specform
specsubform
specspecsubform
defform/ subs
defform*/ subs
specform/ subs
specsubform/ subs
specspecsubform/ subs
defparam
defparam*
defboolparam
defthing
defstruct*
defstruct
deftogether
racketgrammar
racketgrammar*
defidentifier
schemegrammar
schemegrammar*
current-display-width

top ← prev up next →

##### 4.2.3`` Documenting Forms, Functions, Structure Types, and Values

> > syntax
> > (defproc options prototype
> > result-contract-expr-datum
> > maybe-value
> > 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+
> options |  | = |  | maybe-kind maybe-link maybe-id
> maybe-kind |  | = |  |
> |  | | |  | #:kind kind-string-expr
> maybe-link |  | = |  |
> |  | | |  | #:link-target? link-target?-expr
> maybe-id |  | = |  |
> |  | | |  | #:id [src-id dest-id-expr]
> maybe-value |  | = |  |
> |  | | |  | #:value value-expr-datum
> 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. Unless link-target?-expr is specified and produces #f, 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.

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.
> }

> Renders like:

> > > > procedure (make-sandwich ingredients) → sandwich?
> > > > ingredients : (listof ingredient?)

> > > Returns a sandwich given the right ingredients.

> > > > > sandwich-maker
> > > > > (make-reuben |  | ingredient |  |  |  |
> > > > > |  | ... |  |  |  |
> > > > > | [ | #:veggie? veggie?]) |  | → |  | sandwich?
> > > > ingredient : sauerkraut?
> > > > veggie? : any/c = #f

> > > Produces a reuben given some number of ingredients.

> > > If veggie? is #f, produces a standard reuben with corned beef. Otherwise, produces a vegetable reuben.

When id is indexed and registered, 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.

If #:value value-expr-datum is given, value-expr-datum is typeset using racketblock0 and included in the documentation. As a service to readers, please use #:value to document only simple, short functions.

> > syntax
> > (defproc* options
> > ([prototype
> > result-contract-expr-datum
> > maybe-value] ...)
> > pre-flow ...)

Like defproc, but for multiple cases with the same id. 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 (but multiple defprocs grouped by deftogether also works for that case).

When an id has multiple calling cases, either they must be defined with a single defproc*, so that a single definition point exists for the id, or else all but one definition should use #:link-target? #f.

Examples:

> @defproc*[([(make-pb&j) sandwich?]
> [(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.
> }

> Renders like:

> > > > procedure (make-pb&j) → sandwich?
> > > > (make-pb&j jelly) → sandwich?
> > > > jelly : jelly?

> > > Returns a peanut butter and jelly sandwich. If jelly is provided, then it is used instead of the standard (grape) jelly.

> > syntax
> > (defform options form-datum
> > maybe-grammar maybe-contracts
> > pre-flow ...)
> options |  | = |  | maybe-kind maybe-link maybe-id maybe-literals
> maybe-kind |  | = |  |
> |  | | |  | #:kind kind-string-expr
> maybe-link |  | = |  |
> |  | | |  | #:link-target? link-target?-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.

Unless link-target?-expr is specified and produces #f, 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?]
> [ingredient-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.
> }

> Renders like:

> > > > syntax (sandwich-promise sandwich-expr)
> > > > | sandwich-expr |  | : |  | sandwich?

> > > Returns a promise to construct a sandwich. When forced, the promise will produce the result of sandwich-expr.

> > > > > syntax
> > > > > (sandwich-promise* [sandwich sandwich-expr]
> > > > > [mixins ingredient-expr ...])
> > > > > | sandwich-expr |  | : |  | sandwich?
> > > > > | ingredient-expr |  | : |  | ingredient?

> > > Returns a promise to construct a sandwich. When forced, the promise will produce the result of sandwich-expr. Each result of the ingredient-exprs will be mixed into the resulting sandwich.

> > > > syntax (sandwich-factory maybe-name factory-component ...)
> > > > maybe-name |  | = |  |
> > > > |  | | |  | name
> > > > factory-component |  | = |  | #:protein protein-expr
> > > > |  | | |  | [vegetable vegetable-expr]

> > > Constructs a sandwich factory. If maybe-name is provided, the factory will be named. Each of the factory-component clauses adds an additional ingredient to the sandwich pipeline.

> > syntax
> > (defform* options [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.
> }

> Renders like:

> > > > syntax (call-with-current-sandwich expr)
> > > > (call-with-current-sandwich expr sandwich-handler-expr)

> > > Runs expr and passes it the value of the current sandwich. If sandwich-handler-expr is provided, its result is invoked when the current sandwich is eaten.

> > syntax
> > (defform/none maybe-kind maybe-literal form-datum
> > maybe-grammar maybe-contracts
> > pre-flow ...)

Like defform with #:link-target? #f.

> syntax (defidform maybe-kind maybe-link id pre-flow ...)

Like defform, but with a plain id as the form.

> syntax (defidform/inline id)
> (defidform/inline (unsyntax id-expr))

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.

> > syntax
> > (defsubform options form-datum
> > maybe-grammar maybe-contracts
> > pre-flow ...)
> > syntax
> > (defsubform* options [form-datum ...+]
> > maybe-grammar maybe-contracts
> > pre-flow ...)

Like defform and defform*, but with indenting on the left for both the specification and the pre-flows.

> > syntax
> > (specform maybe-literals datum maybe-grammar maybe-contracts
> > pre-flow ...)

Like defform with #:link-target? #f, but with indenting on the left for both the specification and the pre-flows.

> > syntax
> > (specsubform maybe-literals datum maybe-grammar maybe-contracts
> > pre-flow ...)

Similar to defform with #:link-target? #f, but without the initial identifier as an implicit literal, 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.

> > syntax
> > (specspecsubform maybe-literals datum maybe-grammar maybe-contracts
> > pre-flow ...)

Like specsubform, but indented an extra level. Since using specsubform within the body of specsubform already nests indentation, specspecsubform is for extra indentation without nesting a description.

> > syntax
> > (defform/subs options form-datum
> > ([nonterm-id clause-datum ...+] ...)
> > maybe-contracts
> > pre-flow ...)
> > syntax
> > (defform*/subs options [form-datum ...+]
> > ([nonterm-id clause-datum ...+] ...)
> > maybe-contracts
> > pre-flow ...)
> > syntax
> > (specform/subs maybe-literals datum
> > ([nonterm-id clause-datum ...+] ...)
> > maybe-contracts
> > pre-flow ...)
> > syntax
> > (specsubform/subs maybe-literals datum
> > ([nonterm-id clause-datum ...+] ...)
> > maybe-contracts
> > pre-flow ...)
> > syntax
> > (specspecsubform/subs maybe-literals datum
> > ([nonterm-id clause-datum ...+] ...)
> > maybe-contracts
> > pre-flow ...)

Like defform, defform*, specform, specsubform, and specspecsubform, respectively, but the auxiliary grammar is mandatory and the #:grammar keyword is omitted.

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.
> }

> Renders like:

> > > > syntax (sandwich-factory maybe-name factory-component ...)
> > > > maybe-name |  | = |  |
> > > > |  | | |  | name
> > > > factory-component |  | = |  | #:protein protein-expr
> > > > |  | | |  | [vegetable vegetable-expr]

> > > Constructs a sandwich factory. If maybe-name is provided, the factory will be named. Each of the factory-component clauses adds an additional ingredient to the sandwich pipeline.

> > syntax
> > (defparam maybe-link id arg-id
> > contract-expr-datum
> > maybe-value
> > 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?
> #:value empty-sandwich]{
> A parameter that defines the current sandwich for operations that
> involve eating a sandwich. Default value is the empty sandwich.
> }

> Renders like:

> > > > parameter (current-sandwich) → sandwich?
> > > > (current-sandwich sandwich) → void?
> > > > sandwich : sandwich?
> > > > = | empty-sandwich

> > > A parameter that defines the current sandwich for operations that involve eating a sandwich. Default value is the empty sandwich.

> > syntax
> > (defparam* maybe-link id arg-id
> > in-contract-expr-datum out-contract-expr-datum
> > maybe-value
> > pre-flow ...)

Like defparam, but with separate contracts for when the parameter is being set versus when it is being retrieved (for the case that a parameter guard coerces values matching a more flexible contract to a more restrictive one; current-directory is an example).

> > syntax
> > (defboolparam maybe-link id arg-id
> > maybe-value
> > pre-flow ...)

Like defparam, but the contract on a parameter argument is any/c, and the contract on the parameter result is boolean?.

> > syntax
> > (defthing options id contract-expr-datum maybe-value
> > pre-flow ...)
> options |  | = |  | maybe-kind maybe-link maybe-id
> maybe-kind |  | = |  |
> |  | | |  | #:kind kind-string-expr
> maybe-link |  | = |  |
> |  | | |  | #:link-target? link-target?-expr
> maybe-id |  | = |  |
> |  | | |  | #:id id-expr
> maybe-value |  | = |  |
> |  | | |  | #:value value-expr-datum

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.

If #:value value-expr-datum is given, value-expr-datum is typeset using racketblock0 and included in the documentation. Wide values are put on a separate line.

Examples:

> @defthing[moldy-sandwich sandwich?]{
> Don't eat this. Provided for backwards compatibility.
> }
> @defthing[empty-sandwich sandwich? #:value (make-sandwich empty)]{
> The empty sandwich.
> }

> Renders like:

> > > > value moldy-sandwich : sandwich?

> > > Don’t eat this. Provided for backwards compatibility.

> > > > value empty-sandwich : sandwich? = (make-sandwich empty)

> > > The empty sandwich.

> > syntax
> > (defstruct* maybe-link struct-name ([field-name contract-expr-datum] ...)
> > maybe-mutable maybe-non-opaque maybe-constructor
> > pre-flow ...)
> > syntax
> > (defstruct maybe-link struct-name ([field-name contract-expr-datum] ...)
> > maybe-mutable maybe-non-opaque maybe-constructor
> > pre-flow ...)
> maybe-link |  | = |  |
> |  | | |  | #:link-target? link-target?-expr
> struct-name |  | = |  | id
> |  | | |  | (id super-id)
> maybe-mutable |  | = |  |
> |  | | |  | #:mutable
> maybe-non-opaque |  | = |  |
> |  | | |  | #:prefab
> |  | | |  | #:transparent
> |  | | |  | #:inspector #f
> maybe-constructor |  | = |  |
> |  | | |  | #:constructor-name constructor-id
> |  | | |  | #:extra-constructor-name constructor-id
> |  | | |  | #:omit-constructor

Similar to defform or defproc, but for a structure definition. The defstruct* form corresponds to struct, while defstruct corresponds to define-struct.

Examples:

An example using defstruct:

> @defstruct[sandwich ([protein ingredient?] [sauce ingredient?])]{
> A structure type for sandwiches. Sandwiches are a pan-human foodstuff
> composed of a partially-enclosing bread material and various
> ingredients.
> }

> Renders like:

> > > > > struct
> > > > > (struct |  | sandwich (protein sauce)
> > > > #:extra-constructor-name make-sandwich)
> > > > protein : ingredient?
> > > > sauce : ingredient?

> > > A structure type for sandwiches. Sandwiches are a pan-human foodstuff composed of a partially-enclosing bread material and various ingredients.

Additionally, an example using defstruct*:

> @defstruct*[burrito ([salsa ingredient?] [tortilla ingredient?])]{
> A structure type for burritos. Burritos are a pan-human foodstuff
> composed of a @emph{fully}-encolosed bread material and various
> ingredients.
> }

> Renders like:

> > > > struct (struct burrito (salsa tortilla))
> > > > salsa : ingredient?
> > > > tortilla : ingredient?

> > > A structure type for burritos. Burritos are a pan-human foodstuff composed of a fully-encolosed bread material and various ingredients.

> syntax (deftogether [def-expr ...] pre-flow ...)

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
> }

> Renders like:

> > > > value test-sandwich-1 : sandwich?
> > > > value test-sandwich-2 : sandwich?

> > > Two high-quality sandwiches. These are provided for convenience in writing test cases

> syntax (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.

> syntax (racketgrammar* maybe-literals [id clause-datum ...+] ...)

Like racketgrammar, but for typesetting multiple productions at once, aligned around the = and |.

> > procedure
> > (defidentifier |  | id |  |  |  |
> > | [ | #:form? form? |  |  |  |
> > |  | #:index? index? |  |  |  |
> > |  | #:show-libs? show-libs?]) |  | → |  | element?
> id : identifier?
> form? : boolean? = #f
> index? : boolean? = #t
> show-libs? : boolean? = #t

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).

> syntax (schemegrammar maybe-literals id clause-datum ...+)
> syntax (schemegrammar* maybe-literals [id clause-datum ...+] ...)

Compatibility aliases for racketgrammar and racketgrammar*.

> parameter (current-display-width) → exact-nonnegative-integer?
> (current-display-width w) → void?
> w : exact-nonnegative-integer?

Specifies the target maximum width in characters for the output of defproc and defstruct.
top ← prev up next →