Rust 编码规范 V 1.0 beta

P.CMT.03 使用行注释而避免使用块注释

【描述】

尽量使用行注释（// 或 ///），而非块注释。这是Rust社区的约定俗成。

对于文档注释，仅在编写模块级文档时使用 //!，在其他情况使用 ///更好。

说明： #![doc] 和 #[doc] 对于简化文档注释有特殊作用，没有必要通过 rustfmt 将其强制转化为 //! 或 /// 。

【反例】

#![allow(unused)]
fn main() {
// 不符合

/*
 * Wait for the main task to return, and set the process error code
 * appropriately.
 */
mod tests {
    //! This module contains tests

    // ...
}
}

【正例】

当 normalize_comments = true 时：

#![allow(unused)]
fn main() {
// 符合

// Wait for the main task to return, and set the process error code
// appropriately.

// 符合
// 在使用 `mod` 关键字定义模块时，在 `mod`之上使用 `///` 更好。

/// This module contains tests
mod tests {
    // ...
}

// 符合
#[doc = "Example item documentation"]
pub enum Foo {}
}

【rustfmt 配置】