跳到主要内容

文档与 rustdoc

问题​

Rust 的文档系统有什么特色？

答案​

Rust 的 rustdoc 能从源码注释自动生成 HTML 文档，且文档中的代码示例会被自动测试。

文档注释​

/// 解析 CSV 行为字段列表
///
/// # Arguments
///
/// * `line` - 一行 CSV 文本
/// * `delimiter` - 分隔符
///
/// # Returns
///
/// 字段字符串的 Vec
///
/// # Examples
///
/// ```
/// use my_lib::parse_csv_line;
/// let fields = parse_csv_line("a,b,c", ',');
/// assert_eq!(fields, vec!["a", "b", "c"]);
/// ```
///
/// # Panics
///
/// 如果输入包含未闭合的引号
///
/// # Errors
///
/// 此函数不返回错误
pub fn parse_csv_line(line: &str, delimiter: char) -> Vec<String> {
    line.split(delimiter).map(|s| s.trim().to_string()).collect()
}

//! 模块级文档（放在文件顶部）
//! 
//! 这个模块提供 CSV 解析功能。

常用文档段落​

段落说明
# Examples使用示例（会被测试）
# Panics何时会 panic
# Errors何时返回 Err
# Safetyunsafe 函数的安全前提条件

命令​

cargo doc --open        # 生成并打开文档
cargo doc --no-deps     # 不生成依赖的文档
cargo test --doc        # 只运行文档测试
Rust 特色

文档测试是 Rust 的杀手锏：代码示例永远不会过期，因为它们会被编译和运行。这在其他语言中极为罕见。

常见面试问题​

Q1: 文档测试有什么限制？​

答案：

  • 每个文档测试都是独立的 crate，不能访问私有 API
  • 需要写完整的 use 语句
  • 可以用 # 前缀隐藏辅助代码（在文档中不显示但会编译）
/// ```
/// # // 这行在文档中不显示
/// # use my_lib::parse;
/// let result = parse("hello");
/// assert!(result.is_ok());
/// ```

相关链接​