Generating Documentation

Zig generates HTML documentation from doc comments.

zig build-lib src/root.zig -femit-docs
zig build docs        # if your build.zig declares it

The comment forms

//! A module for working with points.

/// A point in two dimensions.
pub const Point = struct {
    /// Horizontal position, in pixels.
    x: i32,
};

Doc comments are Markdown, and only pub declarations appear in the output.

A /// comment in a position where it cannot attach to anything is a compile error, not a warning, so they cannot silently drift away from what they describe.

In build.zig

const docs = b.addInstallDirectory(.{
    .source_dir = lib.getEmittedDocs(),
    .install_dir = .prefix,
    .install_subdir = "docs",
});
b.step("docs", "Generate documentation").dependOn(&docs.step);

Doctests

Because tests are ordinary language constructs, a test block next to a function serves as both a test and an example. Unlike a comment, it cannot go stale without the build noticing. That is the same principle this entire guide is built on.