11.3 Documenting Forms, Functions, Structure Types, and Values
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 scheme-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 schemeblock0.
(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 schemeblock0, 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 scheme, schemeblock, 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.
|
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.
(defform maybe-id maybe-literals form-datum pre-flow ) | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
|
Produces a sequence of flow elements (encapsulated in a splice) to document a syntatic form named by id whose syntax described by form-datum. If no #:id is used to specify id, then form-datum must have the form (id . datum).
The id is indexed, and it is also registered so that scheme-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, 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 scheme, schemeblock, 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).
The typesetting of form-datum preserves the source layout, like schemeblock.
(defform* maybe-id maybe-literals [form-datum ] pre-flow ) |
Like defform, but for multiple forms using the same id.
|
Like defform, but including an auxiliary grammar of non-terminals shown with the id form. Each nonterm-id is specified as being any of the corresponding clause-datums, where the formatting of each clause-datum is preserved.
|
Like defform/subs, but for multiple forms for id.
(defform/none maybe-literal form-datum pre-flow ) |
Like defform, but without registering a definition.
(defidform id pre-flow ) |
Like defform, but with a plain id as the form.
(specform maybe-literals datum 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 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.
|
Like specsubform, but with a grammar like defform/subs.
(specspecsubform maybe-literals datum 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.
|
Like specspecsubform, but with a grammar like defform/subs.
(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.
(defboolparam id arg-id pre-flow ) |
Like defparam, but the contract on a parameter argument is any/c, and the contract on the parameter result is boolean?.
(defthing id contract-expr-datum pre-flow ) |
Like defproc, but for a non-procedure binding.
| |||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
|
Similar to defform or defproc, but for a structure definition.
(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.
(schemegrammar maybe-literals id clause-datum ) | ||||||||||
| ||||||||||
|
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 scheme.
(schemegrammar* maybe-literals [id clause-datum ] ) |
Like schemegrammar, but for typesetting multiple productions at once, aligned around the = and |.