Skip to main content
Version: Zig 0.12.0

Generating Documentation

The Zig compiler comes with automatic documentation generation. This can be invoked by adding -femit-docs to your zig build-{exe, lib, obj} or zig run command. This documentation is saved into ./docs, as a small static website.

Zig's documentation generation makes use of doc comments which are similar to comments, using /// instead of //, and preceding globals.

Here we will save this as x.zig and build documentation for it with zig build-lib -femit-docs x.zig -target native-windows. There are some things to take away here:

  • Only things that are public with a doc comment will appear
  • Blank doc comments may be used
  • Doc comments can make use of subset of markdown
  • Things will only appear inside generated documentation if the compiler analyses them; you may need to force analysis to happen to get things to appear.
const std = @import("std");
const w =;

///**Opens a process**, giving you a handle to it.
pub extern "kernel32" fn OpenProcess(
///[The desired process access rights](
dwDesiredAccess: w.DWORD,
bInheritHandle: w.BOOL,
dwProcessId: w.DWORD,
) callconv(w.WINAPI) ?w.HANDLE;

///spreadsheet position
pub const Pos = struct{
x: u32,
y: u32,

pub const message = "hello!";

//used to force analysis, as these things aren't otherwise referenced.
comptime {
_ = OpenProcess;
_ = Pos;
_ = message;

//Alternate method to force analysis of everything automatically, but only in a test build:
test "Force analysis" {
comptime {

When using a build.zig this may be invoked by setting the emit_docs field to .emit on a CompileStep. We can create a build step to generate docs as follows and invoke it with $ zig build docs.

const std = @import("std");

pub fn build(b: * void {
const mode = b.standardReleaseOptions();

const lib = b.addStaticLibrary("x", "src/x.zig");

const tests = b.addTest("src/x.zig");

const test_step = b.step("test", "Run library tests");

//Build step to generate docs:
const docs = b.addTest("src/x.zig");
docs.emit_docs = .emit;

const docs_step = b.step("docs", "Generate docs");

This generation is experimental and often fails with complex examples. This is used by the standard library documentation.

When merging error sets, the left-most error set's documentation strings take priority over the right. In this case, the doc comment for C.PathNotFound is the doc comment provided in A.

const A = error{

/// A doc comment
const B = error{

/// B doc comment

const C = A || B;