4.5 In-Source Documentation

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

▼ | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

► | 4.5 | In-Source Documentation

4.5.1 | Source Annotations for Documentation
4.5.2 | Extracting Documentation from Source

On this page:

4.5.1`` Source Annotations for Documentation
for-doc
proc-doc/ names
proc-doc
thing-doc
parameter-doc
struct*-doc
struct-doc
form-doc
begin-for-doc
generate-delayed-documents
require/ doc
provide/ doc
4.5.2`` Extracting Documentation from Source
include-extracted
provide-extracted
include-previously-extracted

top ← prev up next →

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

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

> syntax (for-doc require-spec ...)

A require sub-form for bindings that are needed at documentation time (and documentation-expansion time, etc.) instead of run time (and expansion time, etc.). A for-doc import has no effect on a normal use of the library; it affects only documentation extraction.

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.

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

A provide sub-form that exports id with the contract described by contract just like using contract-out.

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.

> syntax (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 ...)

Like proc-doc/names, but supporting contract forms that embed argument identifiers. Only a subset of ->i and ->d forms are currently supported.

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.

> syntax (thing-doc id contract-expr (desc-expr ...))

Like proc-doc, but for an export of an arbitrary value.

> syntax (parameter-doc id (parameter/c contract-expr) arg-id (desc-expr ...))

Like proc-doc, but for exporting a parameter.

> > syntax
> > (struct*-doc struct-name
> > ([field-name contract-expr-datum] ...)
> > maybe-omit-constructor
> > maybe-mutable maybe-non-opaque maybe-constructor
> > (desc-expr ...))
> maybe-omit-constructor |  | = |  |
> |  | | |  | #:omit-constructor

Like proc-doc, but for struct declarations that use struct.

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

> > syntax
> > (struct-doc struct-name
> > ([field-name contract-expr-datum] ...)
> > maybe-omit-constructor
> > maybe-mutable maybe-non-opaque maybe-constructor
> > (desc-expr ...))

Like struct*-doc, but for struct declarations that use define-struct.

> > syntax
> > (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]
> ...)

Like proc-doc, but for an export of a syntactic form. If #:id is provided, then id is the exported identifier, otherwise the exported identifier is extracted from form-datum.

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

Added in version 1.6 of package scribble-lib.

> syntax (begin-for-doc form ...)

Like to begin-for-syntax, but for documentation time instead of expansion time. The forms can refer to binding required with for-doc.

For example, a definition in begin-for-doc can be referenced by a desc-expr in proc-doc/names.

> syntax (generate-delayed-documents)

Causes documentation information to be recorded as a macro that is expanded (along with any for-doc imports) in the module that uses include-extracted or provide-extracted, instead of within (a submodule of) the module that declares the information.

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.

> syntax (require/doc require-spec ...)

A legacy shorthand for (require (for-doc require-spec ...)).

> syntax (provide/doc spec ...)

A legacy alternative to (provide spec ...)

##### 4.5.2`` Extracting Documentation from Source

(require scribble/extract) | package: scribble-lib

> syntax (include-extracted module-path)

Expands to a sequence of documentation forms extracted from module-path, which is expected to be a module that uses scribble/srcdoc (so that the module has a srcdoc submodule).

> syntax (provide-extracted module-path)

Similar to include-extracted, but the documentation is packaged and exported as exported, instead of left inline.

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.

> syntax (include-previously-extracted module-path regexp)

Similar to include-extracted, but instead of referring to the source that contains its own documentation, module-path refers to a module that uses provide-extracted. The include-previously-extracted form expands to documentation forms for all identifiers whose string forms match regexp.
top ← prev up next →