目录

  1. 什么是 Rust 注释
  2. 为什么要使用注释
  3. 注释的类型
  4. 文档注释与生成文档
  5. 注释的最佳实践
  6. 代码示例
  7. 参考资料与出站链接

什么是 Rust 注释

Rust 注释是代码中用于解释程序功能、可读性或记录信息的文本，它们不会被编译器执行。Rust 提供普通注释和文档注释两种形式，用于不同场景。

为什么要使用注释

  • 代码可读性：帮助开发者理解代码意图。
  • 团队协作：为其他开发者提供上下文。
  • 文档生成：自动生成 API 文档。
  • 调试与维护：记录实现细节或临时标记。

注释的类型

  1. 单行注释：
  • 使用 //，注释到行末。
  1. 多行注释：
  • 使用 /* ... */，可跨多行。
  1. 文档注释：
  • 外层文档：///，用于注释后续项（如函数、模块）。
  • 内层文档：//!，用于注释包含它的项（如模块内部）。

文档注释与生成文档

  • 文档注释支持 Markdown 语法，可通过 cargo doc 生成 HTML 文档。
  • 生成文档：
1
cargo doc --open
  • 输出在 target/doc/，浏览器自动打开。

注释的最佳实践

  • 简洁明了：避免冗长，突出重点。
  • 更新同步：代码修改时更新注释。
  • 避免多余：不注释显而易见的代码。
  • 使用文档注释：为公共 API 添加 ///。

代码示例

普通注释

1
2
3
4
5
6
7
8
9
10
fn main() {
    // 打印问候语
    println!("Hello, Rust!");
 
    /*
     * 这是一个多行注释
     * 用于解释复杂逻辑
     */
    let x = 42; // 定义变量 x
}

运行结果：

1
Hello, Rust!

文档注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/// 计算两个整数的和
///
/// # 参数
/// * `a` - 第一个整数
/// * `b` - 第二个整数
///
/// # 返回值
/// 返回 `a` 和 `b` 的和
fn add(a: i32, b: i32) -> i32 {
    a + b
}
 
//! 这是一个模块的内层文档
//! 用于描述模块的整体功能
mod my_module {
    /// 模块内的函数
    pub fn hello() {
        println!("Hello from module!");
    }
}
 
fn main() {
    println!("Sum: {}", add(3, 4));
}

运行结果：

1
Sum: 7
  • 运行 cargo doc --open 后，可在浏览器查看生成的文档。

参考资料与出站链接

  1. 官方文档：
  1. 学习资源：
  1. 社区支持：