Zig Docgen

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha b98761fcfc53 · 16 Oct 2026Report an issue or request a re-scan

• Publisherzolotukhin GitHub userOwner of the repository this skill is read from
• Source folderzolotukhin/zinc/.claude/skills/zig-docgenThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictb98761fcfc53A new audit runs when the source changes
• Repository statusNot archivedLast push 12 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use when adding or editing Zig code in ZINC and you want it to remain compatible with the auto-generated Zig API docs. Covers the comment format, supported tags, parser limitations, section naming, and validation steps…

---
name: zig-docgen
description: Use when adding or editing Zig code in ZINC and you want it to remain compatible with the auto-generated Zig API docs. Covers the comment format, supported tags, parser limitations, section naming, and validation steps needed for reliable HTML, JSON, text, and llms exports.
---

# 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`
   - `Shader Dispatch`
   - `Hardware Detection`
   - `Vulkan Runtime`
   - `Metal Runtime`
   - `Managed Models`
   - `Scheduler`
   - `API Server`
   - `Tool Calling`

7. If you add a new section name or a new public declaration pattern, update `site/src/lib/zig-api-loader.ts` and its tests in `site/src/lib/zig-api-loader.test.ts` in the same change.

8. Keep raw bindings and generated glue out of the authored API surface.
   `src/vulkan/vk.zig` and `src/regression_tests.zig` are intentionally excluded from generated docs (`EXCLUDED_MODULES` in the loader).

9. Files that import build-system modules (`@import("gguf")`, `@import("zinc_rt")`, etc.) cannot have their struct runtime layout (`@sizeOf` / `@alignOf` / `@offsetOf`) extracted by the standalone analyzer, because `zig run` does not resolve those imports. Add such files to `EXCLUDED_STRUCT_EXTRACTOR_MODULES` in the loader so the rest of the struct-layout extraction still succeeds. Their doc summary, field declarations, params, and returns continue to render.

## Good Pattern

```zig
//! Create reusable compute command pools and command buffers.
//! @section Vulkan Runtime
//! The decode runtime uses these wrappers to record dispatches and synchronize compute work.

/// Command pool for allocating command buffers.
pub const CommandPool = struct {
    /// Create a command pool bound to the selected compute queue family.
    /// @param instance Active Vulkan instance and logical device.
    /// @returns A CommandPool ready to allocate compute command buffers.
    pub fn init(instance: *const Instance) !CommandPool {
        // ...
    }
};
```

## Editing Checklist

- Add or update the module `//!` block.
- Add `///` docs for every changed public symbol.
- Add `///` docs for every changed public method inside exported containers.
- Prefer stable, descriptive names because anchors come from symbol names.
- If the code shape stops matching the extractor, update the loader instead of hand-waving it.

## Validation

Run these after doc-related Zig changes:

```bash
zig build test
cd site && bun test
cd site && npm run build
```

Success means:
- no undocumented public symbols in the generated Zig API surface
- HTML docs still build
- JSON, text, and llms exports stay in sync with the Zig source comments

## Coverage Audit

Run this from the repo root to surface every place the contract is violated:

```bash
python3 .claude/skills/zig-docgen/scripts/audit_doc_coverage.py
```

The script walks `src/**/*.zig` and reports four classes of issue:

- `file_no_module_doc` — the file's first non-empty line isn't `//!`
- `file_no_section` — the `//!` block has no `@section X` line
- `symbol_no_doc` — a top-level `pub fn`/`pub const`/`pub var` has no `///` block
  immediately above it
- `method_no_doc` — a `pub fn` inside an exported `struct`/`enum`/`union` lacks a
  `///` block

Exit code is 0 when clean, 1 when issues remain. Full machine-readable report
lands in `/tmp/zig_doc_audit.json`.

### What the audit excludes

- `src/vulkan/vk.zig` — raw Vulkan bindings
- `src/.zig-api-cache/` — generated compiler artifacts (auto-emitted `builtin.zig`)
- `src/shaders/` — SPIR-V shader sources, not Zig
- `src/metal/` — Objective-C bridge for the Metal backend

If you add new generated trees or non-Zig sources under `src/`, extend
`EXCLUDE_DIR_PARTS` in the audit script.

### What the audit doesn't catch (yet)

- `///` blocks that are present but vacuous (just whitespace after the slashes)
- Functions with multi-parameter signatures that omit `@param` tags
- `@returns` missing on functions where the return type is non-trivial
- `@section` values that don't match the canonical taxonomy above
- `pub fn` inside test functions (intentional — test bodies aren't public API)

Treat the audit as a floor, not a ceiling: passing it means you have *some*
doc-block on every public symbol, not that the prose is good.

Excerpt, first 5,726 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/zolotukhin/zinc
git -C zinc checkout b98761fcfc53

Works in

1. 2026-10-16
   ✓SAFE B 89 / 100

   first audit · source b98761fcfc53

Questions about Zig Docgen

• github.com/zolotukhin/zinc/tree/main/.claude/skills/zig-docgen — the audited source at commit b98761fcfc53 and every finding aboveObserved · 16 Oct 2026

Spotted something wrong? Report a correction · Methodology