生成文档

Zig编译器带有自动生成文档的功能。这可以通过在zig build-{exe, lib, obj}或zig run命令中添加femit-docs来调用。这些文档被保存在./docs中，作为一个小型静态网站。

Zig的文档生成利用了doc注释，它类似于注释，使用///而不是//，以及前面的globals。

在这里，我们将把它保存为x.zig'，然后用zig build-lib -femit-docs x.zig -target native-windows'为它建立文档。这里有一些东西需要注意：

• 只有带有文档注释的公开内容才会出现
• 可以使用空白的文档注释
• 文档注释可以使用markdown的子集
• 只有当编译器分析它们时，事情才会出现在生成的文档中；你可能需要强制分析以获得事情的出现。

const std = @import("std");
const w = std.os.windows;

///**打开一个进程**, 获得一个句柄. 
///[MSDN](https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-openprocess)
pub extern "kernel32" fn OpenProcess(
    ///[进程访问权限](https://docs.microsoft.com/en-us/windows/win32/procthread/process-security-and-access-rights)
    dwDesiredAccess: w.DWORD,
    ///
    bInheritHandle: w.BOOL,
    dwProcessId: w.DWORD,
) callconv(w.WINAPI) ?w.HANDLE;

///spreadsheet 位置
pub const Pos = struct{
    ///row
    x: u32,
    ///column
    y: u32,
};

pub const message = "hello!";

//用于强制分析，因为这些东西没有其他参考价值.
comptime {
    _ = OpenProcess;
    _ = Pos;
    _ = message;
}

//另一种方法是自动强制分析一切，但只在测试构建中:
test "Force analysis" {
    comptime {
        std.testing.refAllDecls(@This());
    }
}

使用build.zig时，可以通过在CompileStep上设置emit_docs字段为.emit来调用。我们可以创建一个生成文档的编译步骤，如下所示，然后用$ zig build docs来调用它.

const std = @import("std");

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

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

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

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

    //构建步骤来生成文档:
    const docs = b.addTest("src/x.zig");
    docs.setBuildMode(mode);
    docs.emit_docs = .emit;
    
    const docs_step = b.step("docs", "Generate docs");
    docs_step.dependOn(&docs.step);
}

这种生成方式是试验性的，在复杂的例子中经常失败。这被标准库文档所使用.

当合并错误集时，最左边的错误集的文档字符串优先于右边的。在这种情况下，C.PathNotFound的文档注释是A中提供的文档注释.

const A = error{
    NotDir,

    /// A doc comment
    PathNotFound,
};
const B = error{
    OutOfMemory,

    /// B doc comment
    PathNotFound,
};

const C = A || B;