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

#lang at-exp

enables the @-reader, which is handy for writing documentation expressions.

4.5.1 Source Annotations for Documentation

Documentation information generated by scribble/srcdoc forms are accumulated into a srcdoc submodule. The generated submodule is accessed by the bindings of scribble/extract.

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.

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—that is, the last part of the generated defproc, so the description can refer to the arg-ids using racket.

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.

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.

The maybe-mutable, maybe-non-opaque, and maybe-constructor options are as in defstruct.

See defform for information on options, form-datum, maybe-grammar, and maybe-contracts.

Added in version 1.6 of package scribble-lib.

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.

4.5.2 Extracting Documentation from Source

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.