文档注释 /// ​

核心概念 ​

文档注释(documentation comment)使用 /// 语法,写在函数、结构体、枚举、trait 等项的上方。cargo doc 会将文档注释解析为 HTML 文档,生成类似 docs.rs 上看到的 API 文档。文档注释支持 Markdown 格式,可以包含标题、列表、代码块、链接等。

文档注释中的代码块默认会被当作文档测试(doctest)在 cargo test 时运行,确保文档中的示例代码始终正确。

rust
/// 计算两个数的最大公约数(GCD)
///
/// 使用欧几里得算法,时间复杂度为 O(log(min(a, b)))。
///
/// # 参数
///
/// * `a` - 第一个非负整数
/// * `b` - 第二个非负整数
///
/// # 返回值
///
/// 返回 `a` 和 `b` 的最大公约数。如果两者都为 0,返回 0。
///
/// # 示例
///
/// ```
/// let result = gcd(12, 8);
/// assert_eq!(result, 4);
///
/// let result = gcd(17, 5);
/// assert_eq!(result, 1);
/// ```
///
/// # Panics
///
/// 此函数不会 panic。
pub fn gcd(mut a: u64, mut b: u64) -> u64 {
    while b != 0 {
        let temp = b;
        b = a % b;
        a = temp;
    }
    a
}

fn main() {
    println!("gcd(12, 8) = {}", gcd(12, 8));
    println!("gcd(100, 75) = {}", gcd(100, 75));
}

常用文档段落 ​

rust
/// 一个带有完整文档的函数示例
///
/// 这里是详细的描述段落。第一行是摘要,会显示在列表视图中。
/// 后续段落提供更详细的说明。
///
/// # 参数
///
/// * `input` - 输入字符串,不能为空
/// * `max_len` - 最大长度限制
///
/// # 返回值
///
/// 返回截断后的字符串。如果输入短于 `max_len`,返回原字符串。
///
/// # 示例
///
/// ```
/// let result = truncate("hello world", 5);
/// assert_eq!(result, "hello");
/// ```
///
/// # Errors
///
/// 如果 `input` 为空,返回 `Err("输入不能为空")`。
///
/// # Panics
///
/// 如果 `max_len` 为 0,此函数会 panic。
///
/// # Safety
///
/// (仅用于 unsafe 函数)说明调用者需要保证的安全条件。
pub fn truncate(input: &str, max_len: usize) -> Result<String, &'static str> {
    if input.is_empty() {
        return Err("输入不能为空");
    }
    assert!(max_len > 0, "max_len 不能为 0");
    Ok(input.chars().take(max_len).collect())
}

/// 用户信息结构体
///
/// 存储用户的基本信息,用于身份验证和展示。
///
/// # 示例
///
/// ```
/// let user = User::new("Alice", 30);
/// assert_eq!(user.name(), "Alice");
/// assert_eq!(user.age(), 30);
/// ```
pub struct User {
    /// 用户名称(不可为空)
    name: String,
    /// 用户年龄
    age: u32,
}

impl User {
    /// 创建一个新的 `User` 实例
    ///
    /// # 参数
    ///
    /// * `name` - 用户名称
    /// * `age` - 用户年龄
    pub fn new(name: &str, age: u32) -> Self {
        User {
            name: name.to_string(),
            age,
        }
    }

    /// 获取用户名称的引用
    pub fn name(&self) -> &str {
        &self.name
    }

    /// 获取用户年龄
    pub fn age(&self) -> u32 {
        self.age
    }
}

fn main() {
    let user = User::new("Alice", 30);
    println!("{}: {}", user.name(), user.age());
}
段落标题用途
# 参数 / # Arguments描述函数参数
# 返回值 / # Returns描述返回值
# 示例 / # Examples可运行的代码示例
# Errors描述可能的错误情况
# Panics描述 panic 条件
# Safetyunsafe 函数的安全条件

文档中的链接 ​

rust
/// 配置构建器
///
/// 使用 [`Config::builder`] 创建构建器,然后链式调用方法设置参数。
///
/// 参见 [`Config`] 了解完整的配置结构。
///
/// 内部使用 [`std::collections::HashMap`] 存储配置项。
pub struct ConfigBuilder {
    items: std::collections::HashMap<String, String>,
}

/// 应用配置
///
/// 通过 [`ConfigBuilder`] 构建此结构体。
pub struct Config {
    items: std::collections::HashMap<String, String>,
}

impl Config {
    /// 创建一个新的 [`ConfigBuilder`]
    pub fn builder() -> ConfigBuilder {
        ConfigBuilder {
            items: std::collections::HashMap::new(),
        }
    }
}

fn main() {
    println!("文档中用 [`TypeName`] 创建类型链接");
}

基本示例 ​

rust
/// 一个简单的栈数据结构
///
/// 基于 `Vec` 实现的后进先出(LIFO)栈。
///
/// # 示例
///
/// ```
/// let mut stack = Stack::new();
/// stack.push(1);
/// stack.push(2);
/// assert_eq!(stack.pop(), Some(2));
/// assert_eq!(stack.pop(), Some(1));
/// assert_eq!(stack.pop(), None);
/// ```
pub struct Stack<T> {
    /// 内部存储
    elements: Vec<T>,
}

impl<T> Stack<T> {
    /// 创建一个空栈
    pub fn new() -> Self {
        Stack { elements: Vec::new() }
    }

    /// 将元素压入栈顶
    ///
    /// # 参数
    ///
    /// * `item` - 要压入的元素
    pub fn push(&mut self, item: T) {
        self.elements.push(item);
    }

    /// 从栈顶弹出元素
    ///
    /// 如果栈为空,返回 `None`。
    pub fn pop(&mut self) -> Option<T> {
        self.elements.pop()
    }

    /// 查看栈顶元素但不弹出
    pub fn peek(&self) -> Option<&T> {
        self.elements.last()
    }

    /// 返回栈中元素的数量
    pub fn len(&self) -> usize {
        self.elements.len()
    }

    /// 栈是否为空
    pub fn is_empty(&self) -> bool {
        self.elements.is_empty()
    }
}

fn main() {
    let mut stack = Stack::new();
    stack.push(10);
    stack.push(20);
    stack.push(30);

    while let Some(val) = stack.pop() {
        println!("弹出: {}", val);
    }
}

常见问题 ​

问题一:/// 和 // 有什么区别?

/// 是文档注释,会被 cargo doc 解析生成 HTML 文档,也会被 cargo test 执行其中的代码块。// 是普通注释,只给代码阅读者看,编译器完全忽略。

问题二:文档注释中的代码块默认是什么语言?

默认是 Rust,会被作为文档测试运行。如果不想运行,用 ```ignore 或 ```text 标记。用 ```no_run 表示编译但不运行。

问题三:怎么生成文档?

cargo doc 生成文档到 target/doc/。cargo doc --open 生成后自动在浏览器中打开。cargo doc --no-deps 只生成当前 crate 的文档。

问题四:私有函数的文档注释会被生成吗?

默认不会。cargo doc --document-private-items 可以生成私有项的文档。

适用场景 ​

  • 公共 API 文档:库的公共函数、类型、trait
  • 文档测试:确保示例代码与实现同步
  • crates.io 展示:发布的 crate 会自动在 docs.rs 上生成文档
  • 团队协作:标准化的 API 文档格式

注意事项 ​

  • 文档注释的第一行是摘要,显示在列表中
  • 代码块默认作为测试运行(cargo test)
  • 用 [TypeName] 创建到其他类型的链接
  • cargo doc --open 在浏览器中查看文档
  • 公共 API 都应该有文档注释
  • 结构体字段也可以用 /// 添加文档

总结 ​

文档注释 /// 写在项上方,支持 Markdown 格式,cargo doc 生成 HTML 文档。常用段落包括参数(# Arguments)、返回值(# Returns)、示例(# Examples)、错误(# Errors)和 Panic(# Panics)。代码块默认作为文档测试运行,确保示例始终正确。用 [TypeName] 创建类型间的链接。cargo doc --open 在浏览器中查看,cargo doc --no-deps 只生成当前 crate 的文档。文档注释的第一行是摘要,显示在 API 列表中。