跳转到内容
语言参考Zig 0.17.1官方原文

注释分为三类。普通注释会被忽略,而文档注释和顶层文档注释用于让编译器生成包文档。

comments.zig
const print = @import("std").debug.print;
pub fn main() void {
// Zig 中的注释以 "//" 开头,在下一个 LF 字节(行尾)处结束。
// 下一行是一条注释,不会执行。
//print("Hello?", .{});
print("Hello, world!\n", .{}); // 另一条注释
}
命令行
$ zig build-exe comments.zig
$ ./comments
Hello, world!

Zig 没有多行注释。每一行代码都可以单独进行词法分析。

文档注释

文档注释恰好以三个斜杠开头,即 /// 而非 ////;连续多行文档注释会合并为一条多行文档注释。文档注释用于说明紧随其后的内容。

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
/// 文档注释
//! 顶层文档注释
const std = @import("std");
命令行
$ zig build-obj invalid_doc-comment.zig
/home/alexrp/Sources/ziglang/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 {}
/// 文件结束
命令行
$ zig build-obj unattached_doc-comment.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/unattached_doc-comment.zig:3:1: error: unattached documentation comment
/// End of file
^~~~~~~~~~~~~~~

文档注释可以与普通注释交错排列;其中的普通注释会被忽略。

顶层文档注释

顶层文档注释以两个斜杠和一个感叹号开头,即 //!;它描述的是拥有所在命名空间的类型。

顶层文档注释必须位于命名空间的起始处、所有表达式之前,否则会产生编译错误。

tldoc_comments.zig
//! 提供获取当前日期和时间的函数,支持不同的
//! 精细程度与准确程度。
const S = struct {
//! 除文件创建的隐式结构体之外,其他命名空间中也
//! 允许顶层注释,但这并不十分有用。目前,
//! 生成包文档时会忽略这些注释。
};