7 Attaching Documentation to Exports

(require syntax/docprovide)

(provide-and-document doc-label-id doc-row ...)

doc-row   =   (section-string (name type-datum doc-string ...) ...)     |   (all-from prefix-id module-path doc-label-id)     |   (all-from-except prefix-id module-path doc-label-id id ...)           name   =   id     |   (local-name-id external-name-id)

A form that exports names and records documentation information.

The doc-label-id identifier is used as a key for accessing the documentation through lookup-documentation. The actual documentation is organized into “rows”, each with a section title.

A row has one of the following forms:

• (section-string (name type-datum doc-string ...) ...)

  Creates a documentation section whose title is section-string, and provides/documents each name. The type-datum is arbitrary, for use by clients that call lookup-documentation. The doc-strings are also arbitrary documentation information, usually concatenated by clients.

  A name is either an identifier or a renaming sequence (local-name-id extenal-name-id).

  Multiple rows with the same section name will be merged in the documentation output. The final order of sections matches the order of the first mention of each section.

• (all-from prefix-id module-path doc-label-id)

• (all-from-except prefix-id module-path doc-label-id id ...)

  Merges documentation and provisions from the specified module into the current one; the prefix-id is used to prefix the imports into the current module (so they can be re-exported). If ids are provided, the specified ids are not re-exported and their documentation is not merged.

(lookup-documentation   module-path-v             label-sym)   →   any

module-path-v : module-path?

label-sym : symbol?

Returns documentation for the specified module and label. The module-path-v argument is a quoted module path, like the argument to dynamic-require. The label-sym identifies a set of documentation using the symbol as a label identifier in provide-and-document.