1. 基本注释

// Line comment

/* Block comment */

按照约定, 尽量使用行注释而非块注释

2. 文档注释(Doc Comennts)

cargo doc会调用rustdoc来生成文档, 而这依赖于文档注释的存在

/// Line comment; document the next item
/** Block comment; document the next item */


//! Line comment; document the enclosing item 
/*! Block comment; document the enclosing item !*/

用例子来展示上面两种文档注释的不同:

/// This module contains tests; `Outer comment`
mode tests{

} 

mode tests{
    //! This module contains tests; `Inner comment`
}

3. 文档属性(Doc Attributes)

Doc Attributes等价于文档注释, 但是功能更强大. 譬如当我们需要设置rustdoc的一些控制属性时, 就会更方便. 下面是两者的等价对应关系

/// Outer comment
#[doc = "Out comment"]


//! Inner comment
#![doc = "Inner comment"]

在这里, 其实涉及了rust的Attribute

• Outer attribute: #[attr]
• Inner attribute: #![attr]

4. 常用注释:

// 如果有未使用的import或者变量, 不发出warning
#![allow(unused)] 

注意事项:

在为crate-level添加注释时, 应当使用//!. 而对于mod等其他代码块, 将///放在代码块前面, 下面是一个使用示例:

//! A Simple Hello World Crate

/// This function returns the greeting; Hello, world!
pub fn hello() -> String {
    ("Hello, world!").to_string()
}

#[cfg(test)]
mod tests {
    use super::hello;

    #[test]
    fn test_hello() {
        assert_eq!(hello(), "Hello, world!");
    }
}