4.5 In-Source Documentation
The scribble/srcdoc and scribble/extract libraries support writing documentation within the documented code along with an export contract, similar to using JavaDoc. With this approach, a single contract specification is used both for the run-time contract and the documentation of an exported binding.
The scribble/srcdoc library provides forms for exporting a binding with associated documentation. The scribble/extract library is used to pull scribble/srcdoc-based documentation into a Scribble document (perhaps for multiple libraries).
Although documentation is written with a library’s implementation when using scribble/srcdoc, the documentation creates no run-time overhead for the library. Similarly, typesetting the documentation does not require running the library. The two phases (run time versus documentation time) are kept separate in much the same way that the module system keeps expansion-time code separate from run-time code, and documentation information is recorded in a submodule to be separately loadable from the enclosing module.
For an example use, see this post at blog.racket-lang.org.
4.5.1 Source Annotations for Documentation
|(require scribble/srcdoc)||package: scribble-lib|
Documentation information generated by scribble/srcdoc forms are accumulated into a srcdoc submodule. The generated submodule is accessed by the bindings of scribble/extract.
(for-doc require-spec ...)
Typically, a library that uses scribble/srcdoc includes at least (require (for-doc scribble/base scribble/manual)) to get core Racket forms and basic Scribble functions to use in documentation expressions.
Each require-spec is used in a submodule relative to the enclosing submodule. To access other submodules of the enclosing module, use a module path of the form (submod ".." name ...).
(proc-doc/names id contract arg-specs (desc-expr ...))
arg-specs = ((arg-id ...) ((arg-id default-expr) ...)) | (arg-id ...) contract = (-> arg ... result) | (->* (mandatory ...) (optional ...) result) | (case-> (-> arg ... result) ...) mandatory = contract-expr | keyword contract-expr optional = contract-expr | keyword contract-expr
The arg-spec specifies the names of arguments and the default values, which are not normally written as part of a contract. They are combined with the contract expression to generate the description of the binding in the documentation via defproc. The (arg-id default-expr) pairs specify the names and default values of the optional arguments. If the contract supports optional arguments, then the first arg-specs form must be used, otherwise the second must be used.
The desc-expr is a sequence of documentation-time expressions that
produces prose to describe the exported binding—
The normal requires of the enclosing library are effectively converted into for-label requires when generating documentation, so that identifiers in the contracts are linked to their corresponding documentation. Similarly, any binding that is available in the run-time phase of the enclosing library can be referenced in documentation prose using the racket form.
(proc-doc id contract maybe-defs (desc-expr ...))
contract = (-> result) | (->i (arg ...) (opt ...) maybe-pre [id res]) | (->i (arg ...) (opt ...) maybe-pre (values [id res] ...)) | (->i (arg ...) (opt ...) #:rest rest [id result-expr]) | (->d (arg ...) () maybe-pre (values [id result] ...)) | (->d (arg ...) () maybe-pre [id result]) | (->d (arg ...) () #:rest id rest [id result]) maybe-pre =
| #:pre (pre-id ...) condition maybe-defs =
| (default-expr default-expr ...)
If the sequence of optional arguments, (opt ...) is empty then the maybe-arg-desc must be not be present. If it is non-empty, then it must have as many default expressions are there are optional arguments.
(thing-doc id contract-expr (desc-expr ...))
(parameter-doc id (parameter/c contract-expr) arg-id (desc-expr ...))
(struct*-doc struct-name ([field-name contract-expr-datum] ...) maybe-omit-constructor maybe-mutable maybe-non-opaque maybe-constructor (desc-expr ...))
The maybe-mutable, maybe-non-opaque, and maybe-constructor options are as in defstruct.
(struct-doc struct-name ([field-name contract-expr-datum] ...) maybe-omit-constructor maybe-mutable maybe-non-opaque maybe-constructor (desc-expr ...))
(form-doc options form-datum maybe-grammar maybe-contracts (desc-expr ...))
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] ...)
See defform for information on options, form-datum, maybe-grammar, and maybe-contracts.
Added in version 1.6 of package scribble-lib.
(class*-doc id super (intf-id ...) pre-flow)
The id, super, and intf-id expressions have the same meaning as in defclass.
Added in version 1.30 of package scribble-lib.
(class-doc id super pre-flow)
The id, and super expressions have the same meaning as in defclass.
Added in version 1.30 of package scribble-lib.
(begin-for-doc form ...)
For example, a definition in begin-for-doc can be referenced by a desc-expr in proc-doc/names.
Delaying document generation in this way allows (for-doc (for-label ....)) imports that would otherwise create cyclic module dependencies.
To avoid problems with accumulated for-doc imports across modules, generate-delayed-documents declaration should appear before any for-doc import.
(require/doc require-spec ...)
(provide/doc spec ...)
4.5.2 Extracting Documentation from Source
|(require scribble/extract)||package: scribble-lib|
Use this form in combination with include-previously-extracted when documentation from a single source is to be split and typeset among multiple documentation locations. The provide-extracted form extracts the documentation once, and then include-previously-extracted form extracts documentation for specific bindings as needed.
(include-previously-extracted module-path regexp)