4.2.2 Documenting Modules

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

▼ | 4.2 | Manual Forms

4.2.1 | Typesetting Code
4.2.2 | Documenting Modules
4.2.3 | Documenting Forms, Functions, Structure Types, and Values
4.2.4 | Documenting Classes and Interfaces
4.2.5 | Documenting Signatures
4.2.6 | Various String Forms
4.2.7 | Links
4.2.8 | Indexing
4.2.9 | Bibliography
4.2.10 | Version History
4.2.11 | Miscellaneous
4.2.12 | Index-Entry Descriptions
4.2.13 | Manual Rendering Style

On this page:

defmodule
declare-exporting
defmodulelang
defmodulereader
defmodule*
defmodulelang*
defmodulereader*
defmodule*/ no-declare
defmodulelang*/ no-declare
defmodulereader*/ no-declare

top ← prev up next →

##### 4.2.2`` Documenting Modules

> syntax (defmodule maybe-req one-or-multi option ... pre-flow ...)
> maybe-req |  | = |  |
> |  | | |  | #:require-form content-expr
> one-or-multi |  | = |  | module-spec
> |  | | |  | #:multi (module-spec ...+)
> module-spec |  | = |  | module-path
> |  | | |  | content-expr
> option |  | = |  | #:module-paths (module-path ...)
> |  | | |  | #:no-declare
> |  | | |  | #:use-sources (src-module-path ...)
> |  | | |  | #:link-target? link-target?-expr
> |  | | |  | #:indirect
> |  | | |  | #:lang
> |  | | |  | #:reader
> |  | | |  | #:packages (pkg-expr ...)

Produces a sequence of flow elements (in a splice) to start the documentation for a module—or for multiple modules, if the #:multi form is used.

Each documented module specified as either a module-path (in the sense of require), in which case the module path is typeset using racketmodname, or by a content-expr. The latter case is triggered by the presence of a #:module-paths clause, which provides a plain module-path for each module-spec, and the plain module-path is used for cross-referencing.

If a #:require-form clause is provided and if #:lang and #:reader are not provided, the given expression produces content to use instead of require for the declaration of the module. The #:require-form clause is useful to suggest a different way of accessing the module instead of through require.

Besides generating text, unless #:no-declare appears as an option, this form expands to a use of declare-exporting with module-paths; the #:use-sources clause, if provided, is propagated to declare-exporting. Consequently, defmodule should be used at most once in a section without #:no-declare, though it can be shadowed with defmodules in sub-sections. Use #:no-declare 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

When #:link-target? is omitted or specified with an expression that produces a true value, then the module-paths are also declared as link targets though a part-tag-decl (which means that the defmodule form must appear before any sub-parts). These link targets are referenced via racketmodname, which thus points to the enclosing section, rather than the individual module-paths.

Specifying #:indirect normally makes sense only when #:link-target? is specified with a #f value. Specifying #:indirect makes the module path that is displayed (and that normally refers to some other declaration of the module) use racketmodname with #:indirect.

If #:lang is provided as an option, then the module name is shown after #lang (instead of in a require form) to indicate that the module-paths are suitable for use by either require or #lang. If the module path for require is syntactically different from the #lang form, use #:module-paths to provide the require variant (and make each module-spec a content-expr).

If #:reader is provided, then the module name is shown after #reader to indicate that the module path is intended for use as a reader module.

By default, the package (if any) that supplies the documented module is determined automatically, but a set of providing packages can be specified explicitly with #:packages. Each pkg-expr result is passed on to a function like tt for typesetting. Provide an empty sequence after #:packages to suppress any package name in the output. Each pkg-expr expression is are duplicated for a declare-exporting form, unless #:no-declare is specified.

Each option form can appear at most once, and #:lang and #:reader are mutually exclusive.

The decoded pre-flows introduce the module, but need not include all of the module content.

> syntax (declare-exporting module-path/escape ... maybe-pkgs maybe-sources)
> maybe-pkgs |  | = |  |
> |  | | |  | #:packages (pkg-expr ...)
> maybe-sources |  | = |  |
> |  | | |  | #:use-sources (module-path/escape ...)
> module-path/escape |  | = |  | module-path
> |  | | |  | ,module-path-expr

Associates the module-paths to all bindings defined within the enclosing section, except as overridden by other declare-exporting declarations in nested sub-sections. The list of module-paths before #:use-sources is shown, for example, when the user hovers the mouse over one of the bindings defined within the section. A unquote-escaped ,module-path-expr can be used in place of a module-path to compute the module path dynamically.

More significantly, the first module-path before #:use-sources plus the module-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 module-path.

- If #:use-sources module-paths are supplied, then they are tried in order before the first module-path. The module-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 module-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 module-paths sequence can be empty if module-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 module-paths in #:use-sources provide a binding context for connecting (via hyperlinks) definitions and uses of identifiers.

Supply #:packages to specify the package that provides the declared modules, which is otherwise inferred automatically from the first module-path. The package names are used, for example, by history.

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.

Changed in version 1.1 of package scribble-lib: Added #:packages clause.
Changed in version 1.17: Added support for ,module-path-expr.

> syntax (defmodulelang one-or-multi maybe-sources option ... pre-flow ...)
> (defmodulelang one-or-multi #:module-path module-path
> option ... pre-flow ...)

Equivalent to defmodule with #:lang. The #:module-path module-path is provided, it is converted to #:module-paths (module-path).

> syntax (defmodulereader one-or-multi option ... pre-flow ...)

Equivalent to defmodule with #:reader.

> syntax (defmodule* maybe-req (module-spec ...+) option ... pre-flow ...)
> syntax (defmodulelang* (module-spec ...+) option ... pre-flow ...)
> syntax (defmodulereader* (module-spec ...+) option ... pre-flow ...)

Equivalent to defmodule variants with #:multi.

> syntax (defmodule*/no-declare maybe-req (module-spec ...) option ... pre-flow ...)
> syntax (defmodulelang*/no-declare (module-spec ...) option ... pre-flow ...)
> syntax (defmodulereader*/no-declare (module-spec ...) option ... pre-flow ...)

Equivalent to defmodule variants #:no-declare.
top ← prev up next →