Version: 4.2.1
11.2 Documenting Modules
| (defmodule maybe-req id maybe-sources pre-flow ...) |
| |
| maybe-req | | = | | | | | | | | | #:require-form expr | | | | | | | | maybe-sources | | = | | | | | | | | | #:use-sources (mod-path ...) |
|
Produces a sequence of flow elements (encaptured in a
splice)
to start the documentation for a module that can be
required
using the path
id. The
decoded
pre-flows
introduce the module, but need not include all of the module content.
Besides generating text, this form expands to a use of
declare-exporting with id; the
#:use-sources clause, if provided, is propagated to
declare-exporting. Consequently, defmodule should be
used at most once in a section, though it can be shadowed with
defmodules in sub-sections.
If a #:require-form clause is provided, the given expression
produces an element to use instead of (scheme require) for
the declaration of the module. This is useful to suggest a different
way of accessing the module instead of through require.
Hyperlinks created by schememodname are associated with the
enclosing section, rather than the local id text.
Like
defmodule, but documents
id as a module path
suitable for use by either
require or
#lang.
Like
defmodule, but documents
id as a module path
suitable for use with
#reader.
| (defmodule* maybe-req (id ...+) maybe-sources pre-flow ...) |
|
|
|
Like
defmodule, etc., but introduces multiple module paths instead
of just one.
Like
defmodule*, etc., but without expanding to
declare-exporting. Use this form when you want to provide a
more specific list of modules (e.g., to name both a specific module
and one that combines several modules) via your own
declare-exporting declaration.
| (declare-exporting mod-path ... maybe-sources) |
| |
| maybe-sources | | = | | | | | | | | | #:use-sources (mod-path ...) |
|
Associates the
mod-paths to all bindings defined within the
enclosing section, except as overridden by other
declare-exporting declarations in nested sub-sections. The
list of
mod-paths is shown, for example, when the user hovers
the mouse over one of the bindings defined within the section.
More significantly, the first mod-path plus the
#:use-sources mod-paths determine the binding that
is documented by each defform, defproc, or similar
form within the section that contains the declare-exporting
declaration:
If no #:use-sources clause is supplied, then the
documentation applies to the given name as exported by the first
mod-path.
If #:use-sources mod-paths are supplied, then
they are tried in order. The first one to provide an export
with the same symbolic name and
free-label-identifier=? to the given name is used as
the documented binding. This binding is assumed to be the same
as the identifier as exported by the first mod-path in
the declare-exporting declaration.
The initial mod-paths sequence can be empty if
mod-paths are given with #:use-sources. In that
case, the rendered documentation never reports an exporting module for
identifiers that are documented within the section, but the
mod-paths in #:use-sources provide a binding context
for connecting (via hyperlinks) definitions and uses of identifiers.
The declare-exporting form should be used no more than once
per section, since the declaration applies to the entire section,
although overriding declare-exporting forms can appear in
sub-sections.