Zig Docgen

Zig Docgen

Use this when you touch src/**/*.zig and the public surface should stay extractable by site/src/lib/zig-api-loader.ts.

Authoring Contract

1. Every documentable module starts with //! comments. Required shape:

   • first line: one-sentence summary
   • one //! @section ... line
   • one or more overview lines

2. Every public symbol gets a /// doc block immediately above it. Include:

   • a one-sentence summary first
   • extra description lines after that if needed
   • @param name ... for meaningful parameters
   • @returns ... when the return value matters
   • @note ... for operational caveats

3. Every pub fn inside an exported struct, enum, or union also gets a /// doc block.

4. Keep public API extraction simple. The generator supports:

   • top-level pub const, pub fn, pub var
   • pub fn methods inside exported containers

5. Do not rely on nested public declarations other than methods. Example:

   • pub const Nested = struct {} inside another exported struct is not part of the generated docs today.
   • If it should be documented, promote it to top level or extend the loader and tests.

6. Reuse the existing section names unless you are intentionally changing the docs taxonomy. Current sections (must match SECTION_META slugs in site/src/lib/zig-api-loader.ts):

   • CLI & Entrypoints
   • Model Format & Loading
   • Tokenization
   • Decode Planning
   • Inference Runtime
   • Sampling