20.3 Generated SDK docs
Compiler SDK syntax is generated—document semantics and invariants, not obvious identifiers.
Generated SDK docs
Beskid.Compiler.* SDK sources (including syntax types) are produced by beskid_ast_reflect_gen, not hand-maintained parallel copies. When you document mirrored declarations:
- Explain semantics and non-obvious invariants.
- Do not restate identifier names and types already visible in the signature.
- Never put
@argon struct fields that are not callable parameters.
Mods and analyzers consume the same AST model—lying in SDK docs breaks more than hover text.
Keep generated and authored material distinct
Section titled “Keep generated and authored material distinct”Treat generated SDK output as a view of the source model. Improve the source comment or generator input when the explanation is wrong; do not patch generated copies that will be replaced on the next run. For the contract that makes generated API information consumable by tools, see the api.json standard.