62 lines
2.5 KiB
Racket
62 lines
2.5 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss"
|
|
(for-label syntax/docprovide))
|
|
|
|
@title[#:tag "docprovide"]{Attaching Documentation to Exports}
|
|
|
|
@defmodule[syntax/docprovide]
|
|
|
|
@defform/subs[#:literals (all-from all-from-except)
|
|
(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 @scheme[doc-label-id] identifier is used as a key for accessing
|
|
the documentation through @scheme[lookup-documentation]. The actual
|
|
documentation is organized into ``rows'', each with a section title.
|
|
|
|
A @scheme[row] has one of the following forms:
|
|
|
|
@itemize{
|
|
@item{@scheme[(section-string (name type-datum doc-string ...) ...)]
|
|
|
|
Creates a documentation section whose title is @scheme[section-string],
|
|
and provides/documents each @scheme[name]. The @scheme[type-datum] is arbitrary,
|
|
for use by clients that call @scheme[lookup-documentation]. The
|
|
@scheme[doc-string]s are also arbitrary documentation information,
|
|
usually concatenated by clients.
|
|
|
|
A @scheme[name] is either an identifier or a renaming sequence
|
|
@scheme[(local-name-id extenal-name-id)].
|
|
|
|
Multiple @scheme[row]s 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.}
|
|
|
|
@item{@scheme[(all-from prefix-id module-path doc-label-id)]}
|
|
@item{@scheme[(all-from-except prefix-id module-path doc-label-id id ...)]
|
|
|
|
Merges documentation and provisions from the specified module
|
|
into the current one; the @scheme[prefix-id] is used to prefix the imports
|
|
into the current module (so they can be re-exported). If @scheme[id]s are
|
|
provided, the specified @scheme[id]s are not re-exported and their
|
|
documentation is not merged.}}}
|
|
|
|
@defproc[(lookup-documentation [module-path-v module-path?]
|
|
[label-sym symbol?])
|
|
any]{
|
|
|
|
Returns documentation for the specified module and label. The
|
|
@scheme[module-path-v] argument is a quoted module path, like the
|
|
argument to @scheme[dynamic-require]. The
|
|
@scheme[label-sym] identifies a set of documentation using the symbol
|
|
as a label identifier in @scheme[provide-and-document].}
|
|
|