Overview of Declaration Documentation¶
A DOC <$ ... $> block attaches reader-facing documentation to the declaration
that follows it:
DOC <$
Returns twice the supplied value.
$>
::double INCLUDE_IF(TRUE) FUNCTION(@ARG:value I32): I32
{
RETURN value * 2;
}
For an ordinary named declaration, modifiers occur in this order:
- optional
DOC <$ ... $>; - optional
PRIVATE(...); - the declaration name;
- optional
DOC <$ ... $>if no block precedes the name; - optional
INCLUDE_IF(...); - the declaration kind and definition.
Documentation may also follow the declaration name:
::double DOC <$ Returns twice the supplied value. $> FUNCTION(@ARG:value I32): I32
{
RETURN value * 2;
}
Member documentation follows the same placement:
::counter STRUCT
{
DOC <$ Returns the current counter value. $>
.read FUNCTION() CONST: I32
{
RETURN .value;
}
.value VAR I32;
}
Documentation text should describe the public contract. Compiler query names, AST shapes, and lowering mechanics are not part of a source-facing declaration contract.
Reference¶
See the Declaration Documentation Reference for the complete language rules, constraints, and technical edge cases.