Invocation, options and results
Ссылкаtopaz doc
topaz doc
Ввод
topaz doc accepts no positional source operand. - selects a package containing topaz. and defaults to the current directory.
- is required and must name a nonempty directory path. - selects self or rust, with self as the default. - reports that selection on standard error.
Applicable language and compiler resource options use the common compiler validation rules. - requests package lock verification. Source operands, output-format options, program arguments, missing values, repeated options, and attached values are rejected before documentation generation.
Параметры и конфликты
| Параметр | Значение по умолчанию | Контракт | Конфликты |
|---|---|---|---|
--compiler rust|self | self | compiler selector (default self); rust selects the reference compiler Also rejects combination with --producer, --self-source. | Не перечислены |
--locked | false | Verify topaz.lock before compiling the selected package. | Не перечислены |
--verbose | false | Reports the selected compiler and whether it was explicit or the default. For | Не перечислены |
--root <dir> | . | The explicit source root or package root for this invocation. | Не перечислены |
--out-dir <dir> | Не указано | generate deterministic package docs into --out-dir Required. | Не перечислены |
--language-version <5.21> | 5.21 | language version selector | Не перечислены |
--compiler-memory-mib <MiB> | 8192 | self compiler worker memory budget (8192); overrides TOPAZ_COMPILER_MEMORY_MIB A positive integer is required. Environment input: TOPAZ_COMPILER_MEMORY_MIB. | Не перечислены |
--compiler-time-ms <ms> | 1800000 | self compilation wall-clock budget (1800000); overrides TOPAZ_COMPILER_TIME_MS A positive integer is required. Environment input: TOPAZ_COMPILER_TIME_MS. | Не перечислены |
Каналы вывода
stdout
stderr
Статус завершения
0
Both documentation files were generated and written.
1
Invalid arguments, invalid or unreadable packages, failed lock verification, parsing, resolution or checking errors, invalid compiler export products, compiler resource failures, and directory or output write failures.
Эффекты
The command reads the package, imported sources, dependency content, and documentation comments. It creates the requested output directory if needed.
After successful checking, it writes exports. and then index.. Existing files at those two paths may be replaced. Other files are preserved.
A failure before output writing leaves both output files unchanged. A later I/O failure can leave one updated file or a partial file. The command returns failure and does not report completed documentation.
Documentation generation makes no network requests and does not execute the package, fetch dependencies, or launch a documentation server.
The same compiler and language mode, source and comment bytes, package configuration, and locked dependency identities produce identical documentation bytes. Export ordering is deterministic and output content does not include a generation timestamp.
The completion message includes the selected destination. Path-sensitive diagnostics require identical path inputs for identical text.
Documentation is always a package operation. - verifies the current lock before checking and never updates it. Registry dependencies and Lispex configuration require the applicable locked package checks.
The command leaves the manifest, lock, dependency source, and vendor tree unchanged. The requested output directory does not become the package root.
Operation
СсылкаUse the package root and output directory to select the package and destination.
Option conditions
Ссылка--locked applies to package-mode check, run, emit, build, test, doc, bench, compiler observe, compiler preview. Selected-entry test also accepts it when --root contains topaz.toml.
- cannot be combined with bootstrap - or -
doc requires --out-dir <dir>
Behavior contract
СсылкаCommand behavior
Arguments and rejection
topaz doc accepts no positional source operand. - selects a package containing topaz. and defaults to the current directory.
- is required and must name a nonempty directory path. - selects self or rust, with self as the default. - reports that selection on standard error.
Applicable language and compiler resource options use the common compiler validation rules. - requests package lock verification. Source operands, output-format options, program arguments, missing values, repeated options, and attached values are rejected before documentation generation.
Output
Successful generation leaves standard output empty and reports the output directory on standard error. Parse, resolver, checker, lock, and I/O diagnostics use standard error.
exports. contains the checked public export surface defined by check -. index. contains the package documentation derived from those exports and their source documentation comments.
- is rejected because doc has no JSON console report mode. The exports. artifact is still produced on success because it has a distinct purpose from command presentation.
Exit status
Exit code 0 means both documentation files were generated and written.
Exit code 1 covers invalid arguments, invalid or unreadable packages, failed lock verification, parsing, resolution or checking errors, invalid compiler export products, compiler resource failures, and directory or output write failures.
Filesystem effects
The command reads the package, imported sources, dependency content, and documentation comments. It creates the requested output directory if needed.
After successful checking, it writes exports. and then index.. Existing files at those two paths may be replaced. Other files are preserved.
A failure before output writing leaves both output files unchanged. A later I/O failure can leave one updated file or a partial file. The command returns failure and does not report completed documentation.
Network access
Documentation generation makes no network requests and does not execute the package, fetch dependencies, or launch a documentation server.
Reproducibility
The same compiler and language mode, source and comment bytes, package configuration, and locked dependency identities produce identical documentation bytes. Export ordering is deterministic and output content does not include a generation timestamp.
The completion message includes the selected destination. Path-sensitive diagnostics require identical path inputs for identical text.
Packages and locks
Documentation is always a package operation. - verifies the current lock before checking and never updates it. Registry dependencies and Lispex configuration require the applicable locked package checks.
The command leaves the manifest, lock, dependency source, and vendor tree unchanged. The requested output directory does not become the package root.
Причина
Documentation follows the package's checked public exports. Requiring a package root and explicit destination avoids treating a stray source operand as an undocumented second package or output selection.
The linked public CLI recipe checks the exact displayed argument rejection before the requested operation. It does not execute the successful operation or verify its effects.
Successful documentation generation writes files and requires a package fixture, so it is outside the exact reviewed execution allowlist. The linked recipe exercises rejection of a positional source operand.
Example contract
СсылкаExample contract
The invocation topaz doc main. is expected to exit with 1.
The command has no positional source operand. The adapter-supplied fixture operand is deliberately rejected before its operation; this is an arity example, not a successful doc session.
Причина
Documentation is generated for the selected package and its exported API. Rejecting a source operand avoids implying that the command documents a different entry.
Example
СсылкаArgument-rejection example
Ссылкаfunction identity<T>(value: T) -> T {value}
Ожидаемый результат
Ожидаемый результат
Textual rejection details remain Pending in the reference model. The independent Tools example gate expects exit 1.
The command has no positional source operand. The adapter-supplied fixture operand is deliberately rejected before its operation; this is an arity example, not a successful doc session.
Verification scope
СсылкаObserved with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 1. 3 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.