注释的种类

在 Rust 中，注释分为三类：

  • 代码注释：用于说明某一块代码的功能。读者往往是同一个项目的协作开发者。
  • 文档注释：用于对项目进行描述，公共 API 等用户关心的功能进行介绍，同时还能提供示例代码，读者往往是想要了解项目的人。
  • 包和模块注释：用于说明当前包和模块的功能，方便用户迅速了解一个项目。

代码注释

代码注释方式有两种：

行注释

行注释：以两个斜线 // 开始，注释内容直到改行结束。

1
// 这是一个行内注释

块注释

块注释：以 /* 开始，以 */ 结束，可以跨越多行。

1
2
3
4
/*
* 这是一个
* 块注释
*/

文档注释

在 Rust 中，文档注释（Documentation Comments）是一种特殊的注释，它们被设计用于生成 HTML 文档，这些 HTML 文档展示公有 API 文档注释的内容。

文档行注释

/// 是用于创建文档行注释的一种特殊注释方式，通常放置在 函数、结构体、枚举、方法 等定义的上方。

1
2
3
4
5
6
7
8
9
10
11
12
13
/// `add_one` 将指定值加 1
///
/// # Example
///
/// ```
/// let = arg = 5;
/// let answer = my_crate::add_one(arg);
/// 
/// assert_eq(6, answer);
///```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

文档块注释

/** ... */ 是用于创建文档块注释的一种特殊注释方式，通常放置在 函数、结构体、枚举、方法 等定义的上方。

(注意：这里由于文章 markdown 代码块解析的问题，我在文档块注释的 “``" 的前面加上了///`，而实际的文档块注释是不需要的。)

1
2
3
4
5
6
7
8
9
10
11
12
/** `add_two` 将指定值加 2

/// ```
let arg = 5;
let answer = my_crate::add_two(arg);

assert_eq!(7, answer);
///```
*/
pub fn add_two(x: i32) -> i32 {
    x + 2
}

文档注释注意项

  1. 文档注释需要位于 lib 类型的包中，例如 src/lib.rs。
  2. 文档注释可以使用 markdown 语法，例如 # Examples 的标题，以及 ``` 代码块高亮。
  3. 被注释的对象需要使用 pub 对外可见，文档注释是给用户看的，内部细节不应该暴露。

查看文档注释

运行 cargo doc 可以直接生成 HTML 文档，放入 target/doc 目录下。

运行 cargo doc --open 可以在生成文档后，自动在浏览器打开网页。

上面的文档行注释和文档块注释示例，生成的最终效果如图所示：

文档注释标题的一些常用语法

  • # Examples：用于包含示例代码块的标题。
  • # Panics：用于描述函数可能引发的 panic 情况。
  • # Errors：用于描述函数可能返回的错误情况。
  • # Safety：用于描述使用 unsafe 代码时的使用条件。

包和模块注释

在 Rust 中，包（Package）和模块（Module）的注释通常放置在源文件的顶部，用于描述包或模块的基本信息和功能。

包级别的注释也分为两种：行注释 //! 和块注释 /*! ... */ 。

在 src/lib.rs 包根的最上方，添加：

1
2
3
4
/*! lib包是world_hello二进制包的依赖包，
 里面包含了compute等有用模块 */

pub mod compute;

再在该包根的子模块 src/compute.rs，添加：

1
2
3
4
5
//! 计算一些你口算算不出来的复杂算术题


/// `add_one`将指定值加1
///

运行 cargo doc --open 查看效果：

总结

在 Rust 中，注释分为三个主要类型：代码注释、文档注释、包和模块注释，每个注释类型都拥有两种形式：行注释和块注释。