Rust 中的注释

2021-01-31 | 0 评论 | 0 浏览

Rust 中的注释分为两种：

普通注释 -- 仅做注释用，在编译时编译器会忽略它们。
文档注释 -- 可以通过命令生成 HTML 帮助文档。

普通注释

Rust 的普通注释与 C++ 的风格一样，分为：

单行注释 -- 以 // 开头，// 后的内容都会被注释掉。
块注释 -- 可以注释多行，并且可以嵌套，使用 /* ... */ 将注释内容与代码分隔。

示例：

 1fn main() {
 2    // 这是行注释
 3
 4    /* 这是块注释，
 5    可以注释多行。*/
 6
 7    /*
 8     * 这也是块注释
 9     * 该行前面的星号不是必须的
10     * 但这样比较好看
11     */
12
13    /* 块注释可以嵌套 /* 嵌套有什么用？ */ 我很疑惑 */
14
15    // 块注释可以注释掉一行中间的部分代码，行注释则没有这个能力
16    let x = 5 + /* 90 + */ 5;
17    println!("Is `x` 10 or 100? x = {}", x);
18}

文档注释

文档注释也分为单行注释和块注释，但又有内外之分：

内部文档注释（Inner doc comment）
- 单行注释（以 /// 开头）
- 块注释（用 /** ... */ 分隔）
外部文档注释（Outer doc comment）
- 单行注释（以 //! 开头）
- 块注释（用 /*! ... */ 分隔）

二者的区别：

内部文档注释是对它之后的项做注释，与使用 #[doc="..."] 是等价的。
外部文档注释是对它所在的项做注释，与使用 #![doc="..."] 是等价的。

另外，在文档注释中可以使用 Markdown 语法。

示例：
使用 cargo new comment --lib 创建一个项目，下面的代码 src/lib.rs 是文件中的内容。

 1//! # Comment
 2//! 外部文档注释--描述包含它的项，一般用来编写 Crate 的文档注释。
 3
 4/// - 内部文档注释 -- `outer_module` 的单行注释1
 5/** - 内部文档注释 -- `outer_module` 的块注释1 */
 6pub mod outer_module {
 7
 8    //! - 外部文档注释 -- `outer_module` 的单行注释2
 9    /*! - 外部文档注释 -- `outer_module` 的块注释2 */
10
11    /// - 内部文档注释 -- `inner_module` 的单行注释
12    /** - 内部文档注释 -- `inner_module` 的块注释 */
13    pub mod inner_module {}
14
15    /// 这是代表人类一个结构体
16    pub struct Person {
17        /// 一个人必须有名字
18        name: String,
19    }
20
21    impl Person {
22        /// 返回具有指定名字的一个人
23        ///
24        /// # 参数
25        ///
26        /// * `name` - 字符串切片，代表人的名字
27        ///
28        /// # 示例
29        ///
30        /// ```
31        /// // 在文档注释中，可以编写代码块
32        /// // 如果向 Rustdoc 传递 --test 参数，它还会帮你测试注释文档中的代码！
33        /// use comment::Person;
34        /// let person = Person::new("name");
35        /// ```
36        pub fn new(name: &str) -> Person {
37            Person {
38                name: name.to_string(),
39            }
40        }
41    }
42}