文档
使用 cargo doc 命令在 target/doc 目录下构建文档，使用 cargo doc --open 命令会在浏览器中自动打开文档。
使用 cargo test 命令运行所有测试（包括文档测试），使用 cargo test --doc 命令只运行文档测试。
这些命令会根据需要适当地调用 rustdoc（和 rustc）。
文档注释
文档注释对于需要文档的大型项目非常有用。运行 rustdoc 时，这些注释会被编译成文档。它们用 /// 表示，并支持 Markdown。
#![crate_name = "doc"]
/// A human being is represented here
pub struct Person {
/// A person must have a name, no matter how much Juliet may hate it
name: String,
}
impl Person {
/// Creates a person with the given name.
///
/// # Examples
///
/// ```
/// // You can have rust code between fences inside the comments
/// // If you pass --test to `rustdoc`, it will even test it for you!
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// Gives a friendly hello!
///
/// Says "Hello, [name](Person::name)" to the `Person` it is called on.
pub fn hello(&self) {
println!("Hello, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}要运行测试，首先将代码构建为库，然后告诉 rustdoc 在哪里可以找到该库，以便它可以将其链接到每个 doctest 程序中
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
文档属性
以下是一些与 rustdoc 一起使用的最常见的 #[doc] 属性的示例。
inline
用于内联文档，而不是链接到单独的页面。
#[doc(inline)]
pub use bar::Bar;
/// bar docs
pub mod bar {
/// the docs for Bar
pub struct Bar;
}no_inline
用于防止链接到单独的页面或任何地方。
// Example from libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;hidden
使用此选项告诉 rustdoc 不要将其包含在文档中
// Example from the futures-rs library
#[doc(hidden)]
pub use self::async_await::*;对于文档，rustdoc 被社区广泛使用。它是用于生成 标准库文档 的工具。