ac26fe7554
Also, updates some of the mzlib files to point at `racket/*' libraries rather than to `scheme/*' ones.
61 lines
2.5 KiB
Racket
61 lines
2.5 KiB
Racket
#lang scribble/doc
|
|
@(require "common.rkt" (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 @racket[doc-label-id] identifier is used as a key for accessing
|
|
the documentation through @racket[lookup-documentation]. The actual
|
|
documentation is organized into ``rows'', each with a section title.
|
|
|
|
A @racket[row] has one of the following forms:
|
|
|
|
@itemize[
|
|
@item{@racket[(section-string (name type-datum doc-string ...) ...)]
|
|
|
|
Creates a documentation section whose title is @racket[section-string],
|
|
and provides/documents each @racket[name]. The @racket[type-datum] is arbitrary,
|
|
for use by clients that call @racket[lookup-documentation]. The
|
|
@racket[doc-string]s are also arbitrary documentation information,
|
|
usually concatenated by clients.
|
|
|
|
A @racket[name] is either an identifier or a renaming sequence
|
|
@racket[(local-name-id extenal-name-id)].
|
|
|
|
Multiple @racket[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{@racket[(all-from prefix-id module-path doc-label-id)]}
|
|
@item{@racket[(all-from-except prefix-id module-path doc-label-id id ...)]
|
|
|
|
Merges documentation and provisions from the specified module
|
|
into the current one; the @racket[prefix-id] is used to prefix the imports
|
|
into the current module (so they can be re-exported). If @racket[id]s are
|
|
provided, the specified @racket[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
|
|
@racket[module-path-v] argument is a quoted module path, like the
|
|
argument to @racket[dynamic-require]. The
|
|
@racket[label-sym] identifies a set of documentation using the symbol
|
|
as a label identifier in @racket[provide-and-document].}
|
|
|