文档注释 ///
核心概念
文档注释(documentation comment)使用 /// 语法,写在函数、结构体、枚举、trait 等项的上方。cargo doc 会将文档注释解析为 HTML 文档,生成类似 docs.rs 上看到的 API 文档。文档注释支持 Markdown 格式,可以包含标题、列表、代码块、链接等。
文档注释中的代码块默认会被当作文档测试(doctest)在 cargo test 时运行,确保文档中的示例代码始终正确。
/// 计算两个数的最大公约数(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));
}常用文档段落
/// 一个带有完整文档的函数示例
///
/// 这里是详细的描述段落。第一行是摘要,会显示在列表视图中。
/// 后续段落提供更详细的说明。
///
/// # 参数
///
/// * `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 条件 |
# Safety | unsafe 函数的安全条件 |
文档中的链接
/// 配置构建器
///
/// 使用 [`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`] 创建类型链接");
}基本示例
/// 一个简单的栈数据结构
///
/// 基于 `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 列表中。