文档

用 cargo doc 构建文档到 target/doc。

用 cargo test 运行所有测试（包括文档测试），用 cargo test --doc 仅运行文档测试。

这些命令会恰当地按需调用 rustdoc（以及 rustc）。

文档注释

文档注释对于需要文档的大型项目来说非常重要。当运行 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` - 字符串切片，代表人的名字
  15.     ///
  16.     /// # 示例
  17.     ///
  18.     ///
  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. }
  12. /// 给一个友好的问候！
  13. /// 对被叫到的 `Person` 说 "Hello, [name]" 。
  14. pub fn hello(& self) {
  15.     println!("Hello, {}!", self.name);
  16. }

}

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

  1. john.hello();

}

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

文档属性

下面是一些使用 rustdoc 时最常使用的 #[doc] 属性的例子。

inline

用于内联文档，而不是链接到单独的页面。

  1. #[doc(inline)]
  2. pub use bar::Bar;
  4. /// bar 的文档
  5. mod bar {
  6.     /// Bar 的文档
  7.     pub struct Bar;
  8. }

no_inline

用于防止链接到单独的页面或其他位置。

  1. // 来自 libcore/prelude 的例子
  2. #[doc(no_inline)]
  3. pub use crate::mem::drop;

hidden

使用此属性来告诉 rustdoc 不要包含此项到文档中：

  1. // 来自 futures-rs 库的例子
  2. #[doc(hidden)]
  3. pub use self::async_await::*;

对文档来说， rustdoc 被社区广泛采用。标准库文档也是用它生成的。

参见: