文档注释指南 (Doc Comment Guidance)

文档注释是 Zig 代码的重要组成部分。编译器使用它们来生成文档，并在 IDE 中提供提示。

文档注释语法

• ///：用于文档化紧随其后的声明（函数、结构体、变量等）。
• //!：用于文档化当前模块（通常放在文件顶部）。

最佳实践

1. 第一行: 应该是简洁的摘要，描述该项的功能。
2. 详细描述: 第一行之后可以跟详细的描述，解释参数、返回值、副作用、错误条件等。
3. 示例: 包含代码示例非常有帮助。

示例

/// 计算两个整数的和。
///
/// 如果结果溢出，则由调用者决定是 panic 还是 wrap。
/// 此函数在 ReleaseFast 模式下可能会导致未定义行为。
pub fn add(a: i32, b: i32) i32 {
    return a + b;
}

模块文档

//! 这是一个处理 HTTP 请求的模块。
//! 它支持 GET 和 POST 方法。

const std = @import("std");