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 the "file" collection’s "gif.rkt" source file and the corresponding extraction in "scribblings/gif.scrbl". As that example illustrates, starting the module declaration with
enables the @-reader, which is handy for writing documentation expressions.
|(require scribble/srcdoc)||package: scribble-lib|
(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.
(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 dec-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 ...))
(begin-for-doc form ...)
(require/doc require-spec ...)
(provide/doc spec ...)
|(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)