模块文档 //!
核心概念
模块文档注释使用 //! 语法,写在文件或模块的开头,用于描述整个模块或 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 格式和代码块测试。与 ///(描述紧跟其后的项)的区别在于://! 描述包含它的容器。好的模块文档应包含概述、快速开始示例和功能模块说明。第一行是摘要,显示在模块列表视图中。