Declaration Documentation¶
DOC <$ ... $> attaches reader-facing text to the declaration that
follows it. The documentation becomes declaration metadata; it does not
execute and does not change overload or availability semantics.
Placement¶
For an ordinary named declaration, the components appear in this order:
- optional
DOC <$ ... $>; - optional
PRIVATE(...); - the
.nameor::namedeclaration name; - optional
DOC <$ ... $>if no block precedes the name; - optional
INCLUDE_IF(...); - the declaration kind and definition.
DOC <$
Returns twice the supplied value.
$>
::double INCLUDE_IF(TRUE) FUNCTION(@ARG:value I32): I32
{
RETURN value * 2;
}
Member and type-owned declarations use the same position:
::counter STRUCT
{
DOC <$ Returns the current counter value. $>
.read FUNCTION() CONST: I32
{
RETURN .value;
}
DOC <$ Current mutable count. $>
.value VAR I32;
}
The DOC block may precede the declaration name and any explicit privacy modifier,
or immediately follow the declaration name before INCLUDE_IF(...) and the
declaration kind. Only one DOC block is allowed for one declaration, including
when both positions are used. A block without a following declaration and a block
preceding a scoped PRIVATE block are syntax errors. Declarations inside a scoped PRIVATE block
may each carry their own documentation.
Methods in INTERFACE, GENERIC, and GENERIC_REF declarations accept both
documentation positions. The documentation attaches to the method whether the
method ends with a semicolon or supplies a default body.
Named base declarations and named import declarations accept both positions.
Anonymous bases also accept DOC immediately after .BASE. Import shorthand
accepts documentation before IMPORT. Documentation belongs to the following declaration alone; nested
declarations and subsequent declarations receive their own documentation.
Delimiters and text¶
The opening delimiter is <$ and the closing delimiter is $>:
All text between the delimiters is captured. A dollar sign that is not followed
by > remains ordinary documentation text. Reaching the end of the source file
without $> is a syntax error.
For a multiline block, the indentation of the line containing the closing delimiter is removed from the beginning of each line that has that indentation:
This permits the source block to follow its surrounding indentation without embedding that structural indentation in the stored documentation. Relative indentation beyond the closing delimiter's indentation is preserved.
Whitespace and comments after $> are skipped before parsing the declaration.
Availability and privacy¶
DOC attaches to the declaration before target filtering and privacy checks.
It does not make an unavailable declaration active and does not make a private
declaration public. The ordering with INCLUDE_IF is syntactic: when both are
present, DOC precedes INCLUDE_IF(...).
See Target Availability and Privacy.
Content contract¶
Documentation should describe the programming interface: purpose, parameters, return value, ownership, mutation, lifetime, failure behavior, and important constraints. Compiler query names, AST node layouts, and lowering mechanics are not part of a source-facing declaration contract unless the declaration itself is an explicitly compiler-facing interface.