1. 单行注释（Line Comments）

单行注释使用两个斜杠 // 开始，从该符号到行尾的所有内容都被视为注释。常用于简短说明或临时注释代码。

  • 语法：

    // 这是一个单行注释
fn main() {
    let x = 5; // 这里是行尾注释，解释变量
    println!("x 的值为: {}", x);
}

  • 关键点：

    • 可以放置在代码行的任何位置，包括行尾。
    • 注释不影响编译或运行。
    • 常用于调试：临时注释掉一行代码以测试。

2. 多行注释（Block Comments）

多行注释使用 /* 开始和 */ 结束，可以跨越多行。适合较长的解释或注释大块代码。

  • 语法：

    /* 
这是一个多行注释。
可以跨越多行，
用于详细说明函数或模块。
*/
fn main() {
    println!("Hello, world!");
}

  • 嵌套支持：Rust 支持嵌套多行注释，这在其他语言中不常见。 示例：

    #![allow(unused)]
fn main() {
/* 外层注释
/* 内层注释 */
外层继续 */
}

  • 关键点：

    • 如果忘记关闭 */，编译器会报错。
    • 适合注释整个函数或代码块，但不推荐过度使用，以免代码混乱。

3. 文档注释（Documentation Comments）

文档注释用于生成 API 文档，支持 Markdown 语法，常用于公共 crate 或库。它们会被 cargo doc 工具处理，生成 HTML 文档。

  • 类型：

    • 外层文档注释（Outer Doc Comments）：使用 ///，放置在项（如函数、结构体）之前，用于描述该项。 示例： 
      #![allow(unused)]
fn main() {
/// 计算两个整数的和。
///
/// # 示例
///
/// ```
/// let sum = add(2, 3);
/// assert_eq!(sum, 5);
/// ```
fn add(a: i32, b: i32) -> i32 {
    a + b
}
}
    • 内层文档注释（Inner Doc Comments）：使用 //!，放置在 crate 或模块的开头，用于描述整个 crate 或模块。 示例（在 lib.rs 中）： 
      #![allow(unused)]
fn main() {
//! # My Crate
//!
//! 这是一个示例 crate，提供基本数学函数。
}

  • 关键点：

    • 支持 Markdown：如 # 标题、``` 代码块、[链接] 等。
    • 常见部分：# Examples、# Panics、# Errors、# Safety（用于 unsafe 代码）。
    • 生成文档：运行 cargo doc 生成文档，cargo doc --open 在浏览器中打开。
    • 文档注释也是注释，不会执行，但会影响生成的文档质量。

示例程序：结合使用注释

以下是一个完整示例，展示各种注释类型：

//! # 示例程序：注释的使用
//!
//! 这个模块演示 Rust 中的注释类型。

/// 一个简单的结构体，表示矩形。
#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

/// 计算矩形的面积。
///
/// # 参数
///
/// * `rect` - 矩形的引用。
///
/// # 返回值
///
/// 面积作为 u32。
fn area(rect: &Rectangle) -> u32 {
    // 计算宽度乘高度
    rect.width * rect.height
    /* 如果需要，可以在这里添加更多逻辑，
    但现在保持简单。 */
}

fn main() {
    let rect = Rectangle { width: 30, height: 50 };
    // 打印面积
    println!("面积: {}", area(&rect));
    // TODO: 添加更多功能 // 这是一个待办注释
}

注意事项

  • 注释风格：遵循 Rust 风格指南，使用注释解释“为什么”（why）而非“做什么”（what），因为代码本身已描述“做什么”。
  • 注释代码：注释掉的代码不会编译，但如果语法错误，编译器仍会检查（除非是多行注释中的无效代码）。
  • 性能：注释不影响运行时性能，但过多注释可能降低可读性。
  • 工具集成：在 IDE 如 RustRover 或 VS Code 中，注释会高亮显示，文档注释可提供悬停提示。
  • 最佳实践：为公共 API 添加文档注释；使用 // TODO: 或 // FIXME: 标记待办事项，这些会被工具如 cargo clippy 检测。