注释 (Comments)

Zig 支持 3 种类型的注释。普通注释会被忽略，但文档注释和顶级文档注释会被编译器用来生成包文档。生成的文档目前仍处于实验阶段，可以通过以下命令生成：

Shell: zig test -femit-docs main.zig

普通注释 (Normal Comments)

文件: comments.zig

const print = @import("std").debug.print;
pub fn main() void {
    // Zig 中的注释以 "//" 开头，并在下一个换行符（行尾）处结束。
    // 下面这行是注释，不会被执行。
    //print("Hello?", .{}); 
    print("Hello, world!\n", .{}); // 另一个注释
}

Shell: $ zig build-exe comments.zig

$ ./comments
Hello, world!

Zig 中没有多行注释（例如 C 语言中的 /* */ 注释）。这使得 Zig 具有每一行代码都可以脱离上下文进行标记化（tokenize）的特性。

文档注释 (Doc Comments)

文档注释是以恰好三个斜杠开头的注释（即 /// 但不是 ////）；连续的多个文档注释会合并在一起形成多行文档注释。文档注释用于记录紧随其后的内容。

文件: doc_comments.zig

/// 用于存储时间戳的结构体，精度为纳秒（这是一个
/// 多行文档注释）。
const Timestamp = struct {
    /// 自纪元以来的秒数（这也是一个文档注释）。
    seconds: i64,
    // 有符号，以便我们可以表示 1970 年以前的时间（这不是文档注释）
    /// 秒之后的纳秒数（又是文档注释）。
    nanos: u32,
    /// 返回表示 Unix 纪元的 `Timestamp` 结构体；即
    /// 1970 年 1 月 1 日 00:00:00 UTC 的时刻（这也是一个文档注释）。
    pub fn unixEpoch() Timestamp {
        return Timestamp{ .seconds = 0, .nanos = 0 };
    }
};

文档注释仅允许出现在特定位置；如果文档注释出现在意外位置（例如表达式中间，或紧接在非文档注释之前），则会导致编译错误。

文件: invalid_doc-comment.zig

/// doc-comment
//! top-level doc-comment
const std = @import("std");

Shell: $ zig build-obj invalid_doc-comment.zig

/home/andy/dev/zig/doc/langref/invalid_doc-comment.zig:1:16: error: expected type expression, found 'a document comment'
/// doc-comment
^

文件: unattached_doc-comment.zig

pub fn main() void {}
/// End of file

Shell: $ zig build-obj unattached_doc-comment.zig

/home/andy/dev/zig/doc/langref/unattached_doc-comment.zig:3:1: error: unattached documentation comment
/// End of file
^~~~~~~~~~~~~~~

文档注释可以与普通注释交错使用。目前，在生成包文档时，普通注释会与文档注释合并。

顶级文档注释 (Top-Level Doc Comments)

顶级文档注释是以两个斜杠和一个感叹号开头的注释：//!；它用于记录当前模块。如果顶级文档注释没有放置在容器的开头（在任何表达式之前），则会导致编译错误。

文件: tldoc_comments.zig

//! 该模块提供用于获取当前日期和
//! 时间的函数，具有不同程度的精度和准确性。它不
//! 依赖于 libc，但如果有可用的 libc 函数，它将使用它们。
const S = struct {
    //! 顶级注释允许在模块以外的容器内部使用，
    //! 但这并不是很有用。目前，在生成包
    //! 文档时，这些注释会被忽略。
};