Rust 文档化注释

Rust 提供了强大的文档化注释系统，允许你直接在代码中编写文档，这些文档可以通过 rustdoc 工具生成美观的 HTML 文档。

基本文档注释

Rust 使用三斜杠 /// 进行文档注释：

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

生成文档

使用 cargo doc 命令生成文档：

cargo doc --open

这会生成文档并在浏览器中打开。

文档注释格式

标题和部分

使用 Markdown 风格的标题：

/// # 模块级别文档
/// 
/// 这是模块的总体描述。
/// 
/// ## 子标题
/// 
/// 更详细的部分...

参数文档

/// 将两个数字相加
///
/// # 参数
/// * `a` - 第一个加数
/// * `b` - 第二个加数
///
/// # 返回值
/// 两个参数的和
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

示例代码

使用三个反引号标记代码块：

/// 计算斐波那契数列
///
/// # 示例
/// ```
/// let fifth = fibonacci(5);
/// assert_eq!(fifth, 5);
/// ```
pub fn fibonacci(n: u32) -> u32 {
    match n {
        0 => 0,
        1 => 1,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

错误处理

/// 打开文件并读取内容
///
/// # 错误
/// 如果文件不存在或无法读取，返回错误
///
/// # 示例
/// ```
/// let content = read_file("test.txt").unwrap();
/// println!("{}", content);
/// ```
pub fn read_file(path: &str) -> Result<String, std::io::Error> {
    std::fs::read_to_string(path)
}

模块和 crate 文档

模块文档

在模块文件顶部添加文档：

//! 数学运算模块
//!
//! 这个模块提供基本的数学运算功能

/// 将两个数字相加
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Crate 根文档

在 lib.rs 或 main.rs 顶部添加：

//! # 我的 Rust 库
//!
//! 这是一个演示 Rust 文档的库
//!
//! 包含基本的数学运算和字符串处理功能

特殊部分

Rust 文档支持一些特殊部分：

• # Panics - 描述函数可能 panic 的情况
• # Safety - 描述不安全函数的安全前提条件
• # Examples - 示例代码

/// 分割字符串为两部分
///
/// # Panics
/// 如果分隔符不在字符串中会 panic
///
/// # 示例
/// ```
/// let (left, right) = split_at_middle("abcdef");
/// assert_eq!(left, "abc");
/// assert_eq!(right, "def");
/// ```
pub fn split_at_middle(s: &str) -> (&str, &str) {
    let mid = s.len() / 2;
    (&s[..mid], &s[mid..])
}

文档测试

Rust 会自动运行文档中的代码示例作为测试：

/// 这个函数总是返回 42
///
/// # 示例
/// ```
/// assert_eq!(always_forty_two(), 42);
/// ```
pub fn always_forty_two() -> i32 {
    42
}

运行测试：

cargo test

标记文档

可以使用以下标记增强文档：

• [`TraitName`] - 链接到 trait
• [`struct@StructName`] - 链接到结构体
• [`fn function_name`] - 链接到函数
• [std::io] - 链接到外部 crate 的文档

/// 这个结构体实现了 [`Iterator`] trait
///
/// 有关迭代器的更多信息，请参见 [`std::iter`] 模块
pub struct MyIterator {
    // ...
}

内联文档

使用 //! 为包含它的项添加文档（通常用于模块）：

//! 这是模块的文档
//!
//! 这个模块实现了各种数学运算

/// 加法函数
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

最佳实践

1. 为所有公共项（pub fn, pub struct, pub enum 等）添加文档
2. 包含使用示例
3. 明确说明错误条件和 panic 情况
4. 保持文档与代码同步
5. 使用 cargo doc 定期检查生成的文档

高级特性

隐藏实现细节

使用 # 隐藏代码块不显示在文档中：

/// 复杂计算
///
/// ```
/// # use mylib::complex_calculation;
/// let result = complex_calculation(1.0, 2.0);
/// ```
pub fn complex_calculation(a: f64, b: f64) -> f64 {
    // # 这个部分不会出现在文档中
    a * b + 1.0
}

文档属性

使用 #[doc] 属性：

#[doc = "这是一个替代语法"]
/// 这个函数做...
pub fn something() {}

#[doc(hidden)]
pub fn _internal_function() {}

文档别名

为搜索添加别名：

#[doc(alias = "plus")]
#[doc(alias = "addition")]
/// 将两个数字相加
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

通过良好的文档注释，你可以创建出既易于使用又易于维护的 Rust 代码库。