Rust 文档注释 (Documentation Comments)

1. 文档注释概述

Rust 的文档注释用于为 函数、结构体、枚举、trait、模块、crate 等生成官方 API 文档。

特点：

可通过 cargo doc 生成 HTML 文档。
支持 Markdown 格式。
文档中的代码可以被编译器测试（Doc Test）。
与普通注释 (//, /* */) 不同，专门用于生成可读文档。

2. 注释类型

类型	语法	位置	说明
外层文档注释	`///`	函数、结构体、枚举、trait	为单个项生成文档
模块/文件注释	`//!`	模块或文件顶部	为整个模块或 crate 生成文档
普通注释	`//` 或 `/* */`	任意位置	仅供代码阅读，不生成文档

示例：函数文档注释

#![allow(unused)]
fn main() {
/// 计算两个整数的和
///
/// # 示例
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

示例：模块文档注释

//! utils 模块
//!
//! 提供通用工具函数，例如加减乘除、格式转换等

3. 常用标签（Section Headers）

Rust 文档注释中经常使用 Markdown 风格的标题 来说明函数特性：

标签	用途	示例
`# Examples`	展示函数/方法使用方法	`rust let r = add(1, 2); assert_eq!(r, 3);`
`# Panics`	说明函数可能 panic 的情况	当除数为 0 时 panic
`# Errors`	说明函数可能返回的错误	返回 `Result::Err` 时说明原因
`# Safety`	对 `unsafe` 函数，说明安全要求	调用前必须保证指针有效
`# Arguments`	说明函数参数	`x: i32 - 输入值`
`# Returns`	说明函数返回值	`i32 - 返回和`

示例：带多个标签

#![allow(unused)]
fn main() {
/// 除法函数
///
/// # Arguments
///
/// * `numerator` - 被除数
/// * `denominator` - 除数
///
/// # Panics
///
/// 当 `denominator` 为 0 时会 panic
///
/// # Examples
///
/// ```
/// let result = my_crate::divide(10, 2);
/// assert_eq!(result, 5);
/// ```
pub fn divide(numerator: i32, denominator: i32) -> i32 {
    assert!(denominator != 0);
    numerator / denominator
}
}

4. Doc Test（文档测试）

文档中的 Rust 代码可以直接被 Rust 编译器测试。
代码必须在 rust ... 块中。
编译器会检查示例代码的正确性，保证文档与实际行为一致。

示例：带 Doc Test 的函数

#![allow(unused)]
fn main() {
/// 计算向量元素平方和
///
/// # Examples
///
/// ```rust
/// let v = vec![1, 2, 3];
/// assert_eq!(my_crate::sum_of_squares(&v), 14);
/// ```
pub fn sum_of_squares(v: &Vec<i32>) -> i32 {
    v.iter().map(|x| x*x).sum()
}
}

运行文档测试：

cargo test --doc

5. 模块/Crate 文档

模块顶部用 //! 注释：

#![allow(unused)]
fn main() {
//! utils 模块
//! 提供常用工具函数
}

Crate 顶部（lib.rs 或 main.rs）用 //! 生成 crate 级别文档：

#![allow(unused)]
fn main() {
//! My Crate
//! 提供计算和字符串处理工具
}

支持 Markdown，可以嵌入图片、链接、表格等。

6. Markdown 支持

Rust 文档注释支持：

标题：# 一级, ## 二级
列表：- 或 *
代码块：rust ...
内联代码：`code`
链接： [文本](URL)
表格：标准 Markdown 表格

示例：带表格的文档

#![allow(unused)]
fn main() {
/// 颜色类型
///
/// | 名称 | RGB |
/// |------|-----|
/// | Red  | (255,0,0) |
/// | Green| (0,255,0) |
/// | Blue | (0,0,255) |
pub enum Color {
    Red,
    Green,
    Blue,
}
}

7. 高级示例：结构体和方法

#![allow(unused)]
fn main() {
/// 表示二维点
///
/// # Examples
///
/// ```
/// let p = my_crate::Point::new(3.0, 4.0);
/// assert_eq!(p.magnitude(), 5.0);
/// ```
pub struct Point {
    pub x: f64,
    pub y: f64,
}

impl Point {
    /// 创建新点
    pub fn new(x: f64, y: f64) -> Self {
        Self { x, y }
    }

    /// 计算点到原点的距离
    ///
    /// # Examples
    ///
    /// ```
    /// let p = my_crate::Point::new(3.0, 4.0);
    /// assert_eq!(p.magnitude(), 5.0);
    /// ```
    pub fn magnitude(&self) -> f64 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}
}

8. 自动生成文档

生成 HTML 文档：

cargo doc --open

特点：

文档生成在 target/doc 目录。
支持模块导航、搜索、函数参数和示例。
Doc Test 会自动运行，保证示例可用。

9. 最佳实践

每个公共函数、结构体都写文档。
示例代码完整可运行。
复杂函数标注 # Panics, # Safety, # Errors。
模块顶部写模块概述，crate 顶部写整体概述。
Markdown 排版清晰，列表、标题、表格、代码块分明。
Doc Test 可用性：在文档中引用真实 API，方便测试。

Keyboard shortcuts

Rust study