2.5 注释与文档注释

在 Rust 中，良好的代码可读性不仅依赖于清晰的逻辑，也离不开恰当的注释。Rust 支持多种注释形式，用于解释代码意图、提供上下文或生成自动化文档。

普通注释

普通注释以 // 开头，适用于单行说明：

// 这是一个计算两数之和的函数
fn add(a: i32, b: i32) -> i32 {
    a + b
}

也可以使用 /* ... */ 进行多行注释，但这种形式在 Rust 社区中较少使用：

/*
这个函数目前仅用于演示，
后续可能会扩展功能。
*/
fn demo() {}

普通注释在编译时会被完全忽略，不影响程序行为。

文档注释

Rust 提供了专门用于生成文档的注释语法，称为文档注释。它们以三个斜杠 /// 开头，用于描述紧随其后的项（如函数、结构体、模块等）。这些注释可以通过 cargo doc 命令自动生成 HTML 格式的文档。

例如：

/// 将两个整数相加并返回结果。
///
/// # 示例
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

文档注释支持 Markdown 语法，因此可以包含标题、列表、代码块等格式。# 示例 部分中的代码块不仅用于说明，还可以被 cargo test 自动运行，作为文档测试（doctest）验证示例是否正确。

模块级文档注释

如果想为整个 crate 或模块添加文档，可以使用 //! 注释。这类注释必须出现在文件或模块的顶部，用于描述当前作用域的整体用途。

例如，在 src/lib.rs 文件开头：

//! # My Math Library
//!
//! 该库提供基本的数学运算函数，
//! 包括加法、减法等。
//!
//! ## 使用示例
//!
//! ```
//! use my_math_lib::add;
//! assert_eq!(add(1, 2), 3);
//! ```

//! 注释属于“内部文档注释”，因为它描述的是包含它的文件或模块本身，而不是其后的内容。

查看与生成文档

运行以下命令即可在浏览器中查看本地生成的文档：

cargo doc --open

该命令会递归处理项目及其所有依赖的文档注释，并启动默认浏览器打开入口页面。

小结

合理使用注释不仅能帮助他人理解你的代码，也能提升自己的开发效率。普通注释用于临时说明或调试，而 /// 和 //! 则是构建高质量、可维护 Rust 库的重要工具。通过 cargo doc 自动生成文档，Rust 鼓励开发者将文档视为代码的一部分，实现“代码即文档”的工程实践。