► |  | Scribble: PLT Documentation Tool

1 | How to Scribble Documentation
2 | Scribble Layers
3 | @-Reader
4 | Structures And Processing
5 | Renderer
6 | Decoding Text
7 | Document Language
8 | Document Reader
9 | Basic Document Forms
10 | Scheme
11 | Manual Forms
12 | Evaluation and Examples
13 | BNF Grammars
14 | Cross-Reference Utilities
15 | Text Preprocessor
| Index

▼ | 11 | Manual Forms

11.1 | Typesetting Code
11.2 | Documenting Modules
11.3 | Documenting Forms, Functions, Structure Types, and Values
11.4 | Documenting Classes and Interfaces
11.5 | Documenting Signatures
11.6 | Various String Forms
11.7 | Links
11.8 | Indexing
11.9 | Images
11.10 | Bibliography
11.11 | Miscellaneous
11.12 | Index-Entry Descriptions

On this page:

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

Version: 4.1.4
top← prev up next →

#### 11.2`` Documenting Modules

(defmodule id maybe-sources pre-flow ...)

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.

Hyperlinks created by schememodname are associated with the enclosing section, rather than the local id text.

(defmodulelang id maybe-sources pre-flow ...)

Like defmodule, but documents id as a module path suitable for use by either require or #lang.

(defmodule* (id ...+) maybe-sources pre-flow ...)

Like defmodule, but introduces multiple module paths instead of just one.

(defmodulelang* (id ...+) maybe-sources pre-flow ...)

Like defmodulelang, but introduces multiple module paths instead of just one.

(defmodule*/no-declare (id ...) pre-flow ...)

Like defmodule*, 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.

(defmodulelang*/no-declare (id ...) pre-flow ...)

Like defmodulelang*, but without expanding to declare-exporting.

(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.

top← prev up next →