Rust 中的注释

  |   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}

使用 cargo doc 命令可以生成 Rust 项目的 HTML 帮助文档,上面的示例生成的文档如下图所示:

comment Crate 的文档
comment

outer_module 模块的文档
outer_module

Person 结构体的文档
Person

相关资料

The Rust Reference

The rustdoc book

Rust By Example