模块文档 //! ​

核心概念 ​

模块文档注释使用 //! 语法,写在文件或模块的开头,用于描述整个模块或 crate 的功能和用法。与 ///(外部文档注释,描述紧跟其后的项)不同,//! 是内部文档注释,描述它所在的容器(模块、crate)。

在 src/lib.rs 开头写 //! 注释会成为整个 crate 的文档首页(在 docs.rs 上显示)。在子模块文件开头写 //! 则描述该模块。

rust
//! # My HTTP Client
//!
//! `my_http` 是一个轻量级的 HTTP 客户端库,
//! 支持 GET、POST 等常见请求方法。
//!
//! ## 快速开始
//!
//! ```rust,no_run
//! use my_http::Client;
//!
//! let client = Client::new();
//! let response = client.get("https://example.com").unwrap();
//! println!("{}", response.text());
//! ```
//!
//! ## 功能特性
//!
//! - 同步和异步 API
//! - JSON 序列化/反序列化
//! - 自动重试
//! - 连接池

/// HTTP 客户端
pub struct Client;

impl Client {
    /// 创建一个新的客户端实例
    pub fn new() -> Self {
        Client
    }
}

fn main() {
    println!("//! 用于描述模块或 crate 的整体文档");
}

/// 与 //! 对比 ​

语法名称描述对象位置
///外部文档注释紧跟其后的项函数/结构体/枚举等上方
//!内部文档注释所在的模块/crate文件或模块开头
/** */外部块文档注释紧跟其后的项同 ///
/*! */内部块文档注释所在的模块/crate同 //!
rust
//! 这是模块文档(描述当前模块)

/// 这是函数文档(描述下面的函数)
pub fn example() {}

模块文档的常见结构 ​

rust
//! # crate 名称
//!
//! 简短描述(一两句话概括 crate 的功能)。
//!
//! ## 概述
//!
//! 更详细的说明,包括设计理念、适用场景等。
//!
//! ## 快速开始
//!
//! ```rust
//! // 最简单的使用示例
//! ```
//!
//! ## 功能模块
//!
//! - [`module_a`] - 功能 A 的说明
//! - [`module_b`] - 功能 B 的说明
//!
//! ## Feature Flags
//!
//! | Feature | 说明 |
//! |---------|------|
//! | `json` | 启用 JSON 支持 |
//! | `async` | 启用异步 API |

pub mod module_a {
    //! 功能 A 模块
    //!
    //! 这个模块提供了 A 相关的功能。

    /// A 模块的主要函数
    pub fn do_a() {
        println!("功能 A");
    }
}

pub mod module_b {
    //! 功能 B 模块

    /// B 模块的主要函数
    pub fn do_b() {
        println!("功能 B");
    }
}

fn main() {
    module_a::do_a();
    module_b::do_b();
}

基本示例 ​

rust
//! # 数学工具库
//!
//! 提供常用的数学计算函数,包括阶乘、组合数、最大公约数等。
//!
//! ## 使用示例
//!
//! ```
//! let f = factorial(5);
//! assert_eq!(f, 120);
//!
//! let g = gcd(12, 8);
//! assert_eq!(g, 4);
//! ```

/// 计算阶乘
///
/// 返回 `n!` 的值。`n` 不能超过 20(否则 u64 溢出)。
pub fn factorial(n: u64) -> u64 {
    match n {
        0 | 1 => 1,
        _ => n * factorial(n - 1),
    }
}

/// 计算最大公约数
pub fn gcd(mut a: u64, mut b: u64) -> u64 {
    while b != 0 {
        let temp = b;
        b = a % b;
        a = temp;
    }
    a
}

/// 计算最小公倍数
pub fn lcm(a: u64, b: u64) -> u64 {
    a / gcd(a, b) * b
}

fn main() {
    println!("5! = {}", factorial(5));
    println!("gcd(12, 8) = {}", gcd(12, 8));
    println!("lcm(12, 8) = {}", lcm(12, 8));
}

常见问题 ​

问题一://! 只能写在文件开头吗?

//! 必须写在模块或 crate 的开头(在其他项之前)。如果写在函数或结构体之间,编译器会报错或发出警告。

问题二:lib.rs 和 main.rs 都能用 //! 吗?

都可以。lib.rs 中的 //! 是 crate 文档首页,main.rs 中的 //! 是二进制 crate 的文档。对于库项目,lib.rs 的文档更重要。

问题三:模块文档中的代码块也会被测试吗?

是的。//! 中的代码块和 /// 中的一样,默认作为文档测试运行。用 ignore、no_run 等标记可以控制测试行为。

问题四:怎么在文档中链接到子模块?

用 [`module_name`] 语法。例如 [`crate::utils`] 链接到 utils 模块,[`Config`] 链接到同模块的 Config 类型。

适用场景 ​

  • crate 首页文档:src/lib.rs 开头的 crate 级别文档
  • 模块说明:每个子模块文件开头的模块级别文档
  • 功能概述:描述模块的整体功能和使用方式
  • Feature 说明:列出 crate 支持的 feature flags

注意事项 ​

  • //! 写在文件开头,在所有 use 和项定义之前
  • 第一行是摘要,显示在模块列表中
  • 支持完整的 Markdown 格式
  • 代码块默认作为文档测试运行
  • 用 [`name`] 创建到其他项的链接
  • 好的 crate 文档应包含概述、快速开始和示例

总结 ​

//! 是内部文档注释,用于描述所在的模块或 crate。写在 src/lib.rs 开头时成为 crate 的文档首页,写在子模块文件开头时描述该模块。支持 Markdown 格式和代码块测试。与 ///(描述紧跟其后的项)的区别在于://! 描述包含它的容器。好的模块文档应包含概述、快速开始示例和功能模块说明。第一行是摘要,显示在模块列表视图中。