• 文档

    文档

    文档注释对于需要文档的大型项目来说非常重要。当运行 Rustdoc，这些注释就会编译成文档。它们使用 /// 标记，并支持 Markdown。

    1. #![crate_name = "doc"]
    3. /// 这里给出一个人类
    4. pub struct Person {
    5.     /// 一个人必须有名字，不管 Juliet 多讨厌他/她。
    6.     name: String,
    7. }
    9. impl Person {
    10.     /// 返回给定名字的人
    11.     ///
    12.     /// # 参数
    13.     ///
    14.     /// * `name` - 字符串 slice，代表人物的名称
    15.     ///
    16.     /// # 示例：
    17.     ///
    18.     ///
    1. /// // 可以在注释的特定标记内编写 Rust。
    2. /// // 如果可以通过 --- 测试传递给 Rustdoc，它将会帮你进行测试！
    3. /// let person = Person::new("name);
    4. /// ```
    5. pub fn new(name: &str) -> Person {
    6.     Person {
    7.         name: name.to_string(),
    8.     }
    9. }
    11. /// 给一个友好的问候！
    12. /// 对被叫到的 `Person` 说 "Hello, [name]" 。
    13. pub fn hello(& self) {
    14.     println!("Hello, {}!", self.name);
    15. }

    }

    fn main() {
    let john = Person::new(“John”);

    1. john.hello();

    }

    2. 要运行测试，首先将代码构建为库，然后告诉 `rustdoc` 在哪里找到库，以便它可以将代码链接成各个文档测试程序：
    4. ```bash
    5. $ rustc doc.rs --crate-type lib
    6. $ rustdoc --test --extern doc="libdoc.rs"

    （当你在库 crate 上运行 cargo test 时，Cargo 将自动生成并运行正确的 rustc 和 rustdoc 命令。）