16.4 Doc and api.json
Package documentation is driven by structured api.json—the compiler is the source of truth for signatures and links.
Doc and api.json
beskid doc emits Markdown and api.json under .beskid/docs/. The JSON is not a parallel type system you maintain by hand: signatures, typeRef links, and member hierarchy are compiler-derived. Prose in /// comments attaches to symbols; absence of prose does not remove the symbol from the API graph.
Why this matters for pckg
Section titled “Why this matters for pckg”Registry ingestion and the pckg docs UI treat api.json as the primary contract. If your package page looks empty, the fix is usually “run doc generation and publish,” not “invent a second schema in YAML.”
Authoring tie-in
Section titled “Authoring tie-in”- Write
///on declarations you want explained. - Use
@ref(Qualified.Name)for cross-links the compiler can validate. - Put
@argon callable parameters only—see chapter 20.