注释语法

注释不参与程序运行，却是代码不可缺少的一部分。Rust 有四种注释形式，每种都有不同的用途和使用场景。

行注释 //

行注释是最常见的形式，// 后面到行尾的所有内容都会被编译器忽略：

fn main() {
    // 这是一行注释
    println!("Hello"); // 也可以写在代码行末尾

    // 注释掉的代码不会执行：
    // println!("这行不会输出");
}

Rust 社区的惯例是优先使用行注释，而不是块注释。行注释更清晰、更容易追踪每行的意图。

块注释 /* */

块注释可以跨越多行，常用于临时注释掉一大段代码：

fn main() {
    /*
     * 这是块注释。
     * 缩进和星号只是风格，不是语法要求。
     */

    let x = 5 + /* 90 + */ 5; // 块注释可以嵌入表达式中间！
    println!("x = {}", x);     // 输出 10，不是 100
}

Rust 的块注释有一个独特之处：支持嵌套。

fn main() {
    /* 外层注释
        /* 内层注释也可以 */
    还在外层注释中 */
    println!("块注释可以嵌套");
}

嵌套块注释在 C 语言中是不合法的，但 Rust 支持。这让你可以用 /* */ 快速注释掉已经包含块注释的代码块。

文档注释 ///

/// 用于为紧跟在它后面的代码项（函数、结构体、模块等）生成 HTML 格式的 API 文档，内容支持 Markdown：

/// 计算两个整数的和。
///
/// # 示例
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    println!("{}", add(2, 3));
}

运行 cargo doc --open 后，/// 的内容会渲染成漂亮的网页文档——这是 Rust 生态的标准文档格式，所有开源 crate 都遵循这个惯例。

内部文档注释 //!

//! 与 /// 方向相反——它为包含它的项（通常是文件顶部）生成文档，常用于描述整个模块或 crate：

//! 这是当前模块的描述。
//! 一般放在文件最顶部，用于说明模块的整体用途。

fn main() {
    println!("模块文档注释示例");
}

简单记：/// 是”我在描述下面的东西”，//! 是”我在描述我所在的容器”。

文档注释和内部文档注释的完整用法（Markdown 语法、示例测试、cargo doc 工作流）在项目工程化：文档注释与 doctest 中专门讲解。

四种注释速查

练习题

注释的执行

fn main() {
    // println!("A");
    println!("B");
    /* println!("C"); */
}

块注释的特性

文档注释的方向

哪些注释会生成 API 文档

推荐的注释风格

编程练习

下面的代码本应输出 result = 42，但有一处块注释的位置用错了，把本该参与计算的数字注释掉了。找出问题并修复它。

fn main() {
    let a = 40;
    let b = /* 2 */;
    let result = a + b;
    println!("result = {}", result);
}