Rust 从 0 到 1- 基础概念 - 注释

我比较赞同保持代码的可读性胜于注释，一方面代码的逻辑不会有二义性，另一方面代码永远才是最新的。但是注释还是难免的，在逻辑相对复杂或不易理解时，好的注释有助于我们理解代码。Rust 支持 // 单行注释和  /* */ 多行注释（和 C、Java 一样）。

除了以上两种常见的注释外，Rust 还支持一种 /// 或者 //! 开头的注释，这个官方称为文档注释，用来生成代码 HTML 格式的 crate 文档，类似 Java 的 javadoc ，并且支持 Markdown 语法。参考下面的例子：

//! # calculator//!//! A library for calculate.
/*  comment line 1.  comment line 2.*/pub mod calculator {    /// # Examples    ///    /// ```    /// let arg = 5;    /// let answer = my_crate::add_one(arg);    ///    /// assert_eq!(6, answer);    /// ```    pub fn add_one(x: i32) -> i32 {        // i am a comment        x + 1    } }

/// 和 //! 的区别在于 //! 生成的文档是针对包含该注释的项，一般用于对整个 crate 的描述，而 /// 是针对紧跟在其后的项，一般用于公有 API 的说明（这个在讲到后面 crate 部分的时候再详细说）。

另外，官方建议注释单独一行书写。