注释

注释是代码中的非执行部分，用于解释代码的功能、目的或其他相关信息。

Rust有2种类型的注释: 代码注释 和 文档注释。

代码注释

代码注释用于解释代码的实现细节，帮助开发者理解代码的逻辑和目的。

Rust支持 单行注释 和 多行注释。

单行注释 //

// 这是一个单行注释
let a = 1; // 代码末尾的注释

多行注释 /* */

/* 这是一个
   多行注释
   可以跨越多行 */

let a = 1;

文档注释

文档注释用于为代码生成可读的 HTML 文档(通常用于库的公共 API)，使用 /// 或 //! 符号。

文档注释可以使用Markdown语法，支持标题、列表、代码块等格式，使得生成的文档更易读。使用 cargo doc 命令可以生成HTML格式的文档，方便开发者查看和使用。在 自动化测试 章节会更加详细的介绍。

外部文档注释 ///

用于注释其后面的项(函数、结构体、模块等):

/// 计算两个数的和
///
/// # 参数
/// * `a` - 第一个数字
/// * `b` - 第二个数字
///
/// # 返回值
/// 返回两个数的和
///
/// # 示例
/// ```
/// # use your_crate::add; // 替换为实际的 crate 名称
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

生成的HTML文档页面:

内部文档注释 //!

一般写在文件的最顶部，用于注释其所在的项(通常用于模块或crate):

//! 这是一个计算模块
//!
//! 提供基本的数学运算功能
// 以上内容在生成的文档中会被作为该模块(Module)的整体介绍.

pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

生成的HTML文档页面:

如果你在写具体的工具(函数)，用 ///；如果你在写模块或crate的说明，用 //!