文档

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

  1. #![crate_name = "doc"]
  2. /// 这里给出一个人类
  3. pub struct Person {
  4. /// 一个人必须有名字,不管 Juliet 多讨厌他/她。
  5. name: String,
  6. }
  7. impl Person {
  8. /// 返回具有指定名字的一个人
  9. ///
  10. /// # 参数
  11. ///
  12. /// * `name` - 字符串切片,代表人物的名称
  13. ///
  14. /// # 示例
  15. ///
  16. ///
  1. /// // 在文档注释中,你可以书写代码块
  2. /// // 如果向 Rustdoc 传递 --test 参数,它还会帮你测试注释文档中的代码!
  3. /// use doc::Person;
  4. /// let person = Person::new("name");
  5. /// ```
  6. pub fn new(name: &str) -> Person {
  7. Person {
  8. name: name.to_string(),
  9. }
  10. }
  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();

}

  1. 要运行测试,首先将代码构建为库,然后告诉 `rustdoc` 在哪里找到库,这样它就可以
  2. 使每个文档中的程序链接到库:
  3. ```bash
  4. $ rustc doc.rs --crate-type lib
  5. $ rustdoc --test --extern doc="libdoc.rlib" doc.rs

(当你对库 crate 上运行 cargo test 时,Cargo 将自动生成并运行正确的 rustcrustdoc 命令。)