Add a notation subsection for structs

This commit is contained in:
Asumu Takikawa 2013-08-26 16:16:45 -04:00
parent 20b77f9a8e
commit 5faef8fb06

View File

@ -233,6 +233,47 @@ The brackets around the @racket[_extract-key] and
before. The contract section of the header shows the default values
that are provided for these keyword arguments.
@; ----------------------------------------
@section{Notation for Structure Type Documentation}
A @tech{structure type} is also documented using contract notation:
@nested[#:style 'inset
@defstruct*[#:link-target? #f
color ([red (and/c natural-number/c (<=/c 255))]
[green (and/c natural-number/c (<=/c 255))]
[blue (and/c natural-number/c (<=/c 255))]
[alpha (and/c natural-number/c (<=/c 255))])]
]
The structure type is typeset as it were declared in
the source code of a program using the @racket[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 @racket[_color] has
four fields: @racket[_red], @racket[_green], @racket[_blue],
and @racket[_alpha]. The constructor for the structure type
accepts field values that satisfy
@racket[(and/c natural-number/c (<=/c 255))], i.e., non-negative
exact integers up to 255.
Additional keywords may appear after the field names in the
documentation for a structure type:
@nested[#:style 'inset
@defstruct*[#:link-target? #f
data-source
([connector (or/c 'postgresql 'mysql 'sqlite3 'odbc)]
[args list?]
[extensions (listof (list/c symbol? any/c))])
#:mutable]
]
Here, the @racket[#:mutable] keyword indicates that the fields of
instances of the @racket[_data-source] structure type can be
mutated with their respective setter functions.
@; ----------------------------------------
@section{Notation for Parameter Documentation}