前言
和其他编程语言一样，Rust 也提供了代码注释的功能，注释用于解释代码的作用和目的，帮助开发者理解代码的行为，编译器在编译时会忽略它们。
单行注释
单行注释以两个斜杠 (//) 开始，只影响它们后面直到行末的内容。单行注释通常用于对代码行或代码块的短小说明。
// 这是单行注释的示例
fn main() {
// 编译器会忽略这里的注释
let x = 5; // 这是一个变量声明
}
多行注释
多行注释以一对 /* 和 */ 符号之间的任何文本。它们可以跨越多行，并且可用于注释大块的代码或文本。
/*
这是一个多行注释的示例。
它可以跨越多行。
*/
fn main() {
let y = 10;
/*
下面的代码虽然被注释，但可以展示一个代码块的结构：
if y > 5 {
println!("y is greater than 5");
}
*/
}
值得注意的是，多行注释可以嵌套，这是 Rust 中的一个特性，允许在已经被注释的部分再添加注释。
/*
这是外层的多行注释。
/* 这是内层的多行注释 */
*/
文档注释
在 Rust 中，文档注释不仅对代码的阅读者提供了有价值的指导和解释，它们还被用来生成库的文档。这是通过 rustdoc 工具操作的，rustdoc 是 Rust 的官方文档生成工具，它能够从源代码中的文档注释生成 HTML 文档。
单行文档注释
单行文档注释使用三个正斜杠 ///。通常用来说明单个函数、结构体、枚举、模块或其他项：
/// 加上两个数
///
/// # Arguments
/// * `a` - A i32
/// * `b` - A i32
///
/// # Returns
/// * A i32
///
/// # Examples
/// ```
/// use docs_demo::math::add;
/// let a = 1;
/// let b = 2;
/// assert_eq!(add(a, b), 3);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
如果你的 IDE 支持的话，调用函数时可以看到函数注释，这里用的 VS Code 演示如下:
在上面的示例中，从 /// 开始的行，直到函数定义之前的部分都将成为这个函数的文档注释。rustdoc 工具将会捕获这些注释并用它们生成 HTML 文档。
多行文档注释
多行文档注释使用 /** ... */。如果注释说明比较长或者需要分段，那么这种方式就很有用：
/**
处理特定任务并返回结果的函数。
# 注意
这个函数对输入参数有特定的限制，比如...
# 示例
```
let output = another_function(10);
println!("输出值: {}", output);
```
*/
fn another_function(param: i32) -> i32 {
param * 2
}
模块注释
在模块或文件级别，可以使用 //! 来为整个模块或文件添加文档注释：
//! math crate
//!
//! `math` 是一个演示如何使用文件级文档注释的例子
//!
//! 它包含以下两个函数。
//! - add
//! - subtract
这通常位于文件的开始或模块的顶部。rustdoc 会将这一部分作为整个模块或 crate 的文档。
Markdown 支持
Rust 的文档注释支持使用 Markdown 语法来格式化文本。可以使用 Markdown 来添加标题、列表、代码块等格式化元素。rustdoc 工具将会解析 Markdown 来生成具有排版的文档。
生成文档
要生成文档，可以在项目目录下运行 cargo doc 命令。这会把 Rust 包以及其依赖项生成 HTML 文档，并将其放在 target/doc/<project name> 目录下。
target
├── CACHEDIR.TAG
├── debug
└── doc
├── crates.js
├── docs_demo
│ ├── all.html
│ ├── fn.main.html
│ ├── index.html # rust doc 入口文件
│ ├── math
│ └── sidebar-items.js
├── help.html
├── search-index.js
├── settings.html
├── src
├── src-files.js
└── static.files
双击 index.html 浏览器打开后，呈现页面如下：
结语
通过编写清晰和详细的文档注释，可以使代码更易于理解，并帮助其他开发者更好地利用你的代码或库。
参考资料
- rust 圣经：https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
- rust 实例：https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html
- rustdoc: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html
- rust RFC: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text
