rust 语法和语义 05 注释

rust 语法和语义 05 注释

注释：comments

rust的注释主要分为两类：

行注释 line comments

和

文档注释 doc comments

。

行注释 line comments

同

c

一样，使用

//

开头。

// Line comments are anything after ‘//’ and extend to the end of the line.

let x = 5; // This is also a line comment

// If you have a long explanation for something,
// you can put line comments next to each other.
// Put a space between the // and your comment so that it’s
// more readable.

整段注释

同

c

一样，使用

/* */

表示。

/*
this is block comments,
you can put line comments next to each other.
*/

文档注释 doc comments

使用

///

表示文档注释 。并内建

Markdown

标记支持。

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(6, add_one(5));
/// # fn add_one(x: i32) -> i32 {
/// #     x + 1
/// # }
/// ```
fn add_one(x: i32) -> i32 {
x + 1
}

包含项注释

使用

//!

注释那些包含这个注释的

crate，mod，或者function

。而不是位于注释以后的内容。

经常用于

crate的根文件 lib.rs

或者

模块的根文件 mod.rs

。

//! # The Rust Standard Library
//!
//! The Rust Standard Library provides the essential runtime
//! functionality for building portable Rust software

文档注释生成

可以使用

rustdoc

工具来将文档注释生成为 HTML 文档，也可以将代码示例作为测试运行！

参考

The Rust Programming Language

Rust 程序设计语言（第一版） 简体中文版