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]
注意事项:
在为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!");
}
}