4.3.2 Documenting Modules

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 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 racketmodname are associated with the enclosing section, rather than the local id text.

More significantly, the first mod-path before #:use-sources plus the mod-paths after #:use-sources 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 before the first mod-path. The mod-path that provides 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.

Use #:use-sources sparingly, but it is needed when

• bindings are documented as originating from a module M, but the bindings are actually re-exported from some module P; and

• other documented modules also re-export the bindings from P, but they are documented as re-exporting from M.

For example, the parameterize binding of mzscheme is documented as re-exported from racket/base, but parameterize happens to be implemented in a private module and re-exported by both racket/base and mzscheme. Importing parameterize from mzscheme does not go through racket/base, so a search for documentation on parameterize in mzscheme would not automatically connect to the documentation of racket/base. To make the connection, the documentation of racket/base declares the private module to be a source through #:use-sources, so that any re-export of parameterize from the private module connects to the documentation for racket/base (unless a re-export has its own documentation, which would override the automatic connection when searching for documentation).

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.