Rust 文档

文档是软件项目的重要组成部分，Rust 提供了强大的文档生成工具。本章节将介绍 Rust 中的文档生成方法。

文档注释

行级文档注释

使用 /// 进行行级文档注释：

/// 计算两个数的和
/// 
/// # 参数
/// * `a` - 第一个加数
/// * `b` - 第二个加数
/// 
/// # 返回值
/// 返回两个数的和
/// 
/// # 示例
/// ```rust
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(-1, 1), 0);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

块级文档注释

使用 /** ... */ 进行块级文档注释：

/**
 * 计算两个数的差
 * 
 * # 参数
 * * `a` - 被减数
 * * `b` - 减数
 * 
 * # 返回值
 * 返回两个数的差
 * 
 * # 示例
 * ```rust
 * assert_eq!(subtract(5, 3), 2);
 * assert_eq!(subtract(1, 1), 0);
 * ```
 */
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

模块文档注释

使用 //! 或 /*! ... */ 为模块添加文档注释：

//! 这是一个数学工具模块
//! 
//! 提供了基本的数学运算函数

/// 计算两个数的和
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// 计算两个数的差
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

生成文档

生成本地文档

使用 cargo doc 命令生成文档：

cargo doc

这将生成文档，位于 target/doc/ 目录。

在浏览器中打开文档

使用 cargo doc --open 命令在浏览器中打开文档：

cargo doc --open

包含所有依赖的文档

使用 cargo doc --no-deps 命令只生成当前 crate 的文档，使用 cargo doc --all 命令生成所有依赖的文档：

cargo doc --all

文档测试

Rust 支持在文档中编写测试代码：

/// 计算两个数的和
/// 
/// # 示例
/// ```rust
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(-1, 1), 0);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

运行文档测试：

cargo test --doc

文档格式

标题

使用 # 标记标题：

/// # 函数名称
/// 
/// 函数描述

列表

使用 - 或 * 标记列表项：

/// # 参数
/// * `a` - 第一个参数
/// * `b` - 第二个参数

代码块

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

/// # 示例
/// ```rust
/// assert_eq!(add(2, 3), 5);
/// ```

链接

使用 [链接文本](链接地址) 标记链接：

/// 查看 [Rust 文档](https://doc.rust-lang.org/)

强调

使用 *强调文本* 标记强调文本：

/// *注意*：这是一个重要的提示

文档生成工具

rustdoc

rustdoc 是 Rust 的文档生成工具，cargo doc 命令内部使用它。

mdbook

mdbook 是一个用于创建书籍的工具，也可以用于创建项目文档：

cargo install mdbook
mdbook init my-book
mdbook build
mdbook serve

最佳实践

1. 为所有公共 API 添加文档：确保所有公共函数、结构体和 trait 都有文档。

2. 使用一致的文档风格：使用一致的文档格式和风格。

3. 添加示例：在文档中添加使用示例。

4. 运行文档测试：确保文档中的示例能够正常运行。

5. 使用文档注释：使用 ///、/** ... */ 和 //! 进行文档注释。

6. 发布文档：将文档发布到 docs.rs。

总结

• 文档注释：使用 ///、/** ... */ 和 //! 进行文档注释
• 生成文档：使用 cargo doc 命令生成文档
• 文档测试：在文档中编写测试代码并运行
• 文档格式：使用 Markdown 格式编写文档
• 文档生成工具：rustdoc 和 mdbook
• 最佳实践：为所有公共 API 添加文档，使用一致的文档风格，添加示例，运行文档测试

文档是软件项目的重要组成部分，良好的文档可以帮助用户理解和使用你的代码。通过本章节的学习，你应该已经掌握了 Rust 中的文档生成方法。