Rust 文档：高级技术与工具

引言：为什么 Rust 中的文档不仅仅是注释

Rust 生态系统以其严谨性和可靠性而闻名。然而，即使是最优雅的代码，如果没有高质量的文档也毫无用处。在初级阶段，为公共函数写几行 /// 注释就足够了。但当你的项目扩展到包含数十个模块的多个 crate 时，就需要考虑高级文档编写技术了。

在本文中，我们将探讨一些工具和技巧，帮助你创建企业级的文档：从示例的自动测试到书籍生成以及与 CI/CD 的集成。

1. Doctests：不会撒谎的文档

rustdoc 的主要“亮点”是能够将可执行的代码示例直接嵌入到注释中。这些示例会在运行 cargo test 时自动编译和执行。这确保了你的文档始终是最新的。

基础 doctest

/// 返回两个数的和。////// # 示例////// ```/// let result = my_crate::add(2, 3);/// assert_eq!(result, 5);/// ```pub fn add(a: i32, b: i32) -> i32 {    a + b}

Doctest 的高级技巧

你可以使用 # 隐藏不应在文档中显示的设置行：

/// # 带初始化的示例////// ```/// # use std::collections::HashMap;/// let mut map = HashMap::new();/// map.insert("key", 42);/// assert_eq!(map.get("key"), Some(&42));/// ```

你还可以检查代码是否无法编译（例如，演示编译时错误）：

/// ```compile_fail/// let x: i32 = "строка"; // 错误：类型不匹配/// ```

2. 文档属性：控制与元数据

#[doc(...)] 属性允许你精细地控制文档的显示方式。

隐藏元素

/// 内部函数，不供公开使用。#[doc(hidden)]pub fn internal_helper() {}

分类与搜索

/// 一组用于网络操作的实用工具。#[doc(alias = "net")]#[doc(alias = "socket")]pub mod network {    // ...}

从其他位置嵌入文档

/// 有关一般信息，请参阅[模块文档](index.html)。#[doc(include = "docs/faq.md")]pub fn complex_function() {}

3. 交叉引用与导航

Rustdoc 支持链接到文档中的其他元素。这创建了一个连贯的结构，便于阅读。

链接到函数和类型

/// 使用 [`Config::new`] 创建实例。////// 如需更复杂的配置，请参阅 [`config`] 模块。pub struct Config { /* ... */ }

链接到外部 crate

/// 此函数使用 [serde_json] 进行序列化。////// [serde_json]: https://docs.rs/serde_jsonpub fn to_json() {}

4. 大型项目的工具：mdBook 和 crate 文档

当仅靠 cargo doc 不够用时，mdBook 就派上了用场——这是一个用 Markdown 文件创建书籍的工具。它非常适合编写指南、教程和架构文档。

mdBook 快速入门

# 安装cargo install mdbook

# 创建项目mdbook init my-bookcd my-bookmdbook serve --open

与 rustdoc 集成

你可以使用 #[doc = include_str!()] 属性将 mdBook 的文档嵌入到 cargo doc 中：

/// # 架构////// 库架构的详细描述：///#[doc = include_str!("../docs/architecture.md")]pub mod core {    // ...}

结论