Rust 中的注释
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 的文档:
outer_module 模块的文档:
Person 结构体的文档: