ドキュメント
cargo doc を使用すると、target/doc にドキュメントをビルドできます。cargo doc --open は、それを Web ブラウザーで自動的に開きます。
cargo test を使用すると、すべてのテスト（ドキュメントテストを含む）を実行できます。また、cargo test --doc を使用すると、ドキュメントテストのみを実行できます。
これらのコマンドは、必要に応じて適切に rustdoc（および rustc）を呼び出します。
ドキュメントコメント
ドキュメントコメントは、ドキュメントが必要な大規模プロジェクトで非常に有用です。 rustdoc を実行すると、これらのコメントがコンパイルされてドキュメントになります。 これらは /// で示され、Markdown をサポートしています。
#![crate_name = "doc"]
/// ここでは人間を表します
pub struct Person {
/// Juliet がどれほどそれを嫌っていても、人には名前が必要です
name: String,
}
impl Person {
/// 指定された名前を持つ person を作成します。
///
/// # 例
///
/// ```
/// // コメント内のフェンスの間に Rust コードを記述できます
/// // `rustdoc` に --test を渡すと、それをテストすることさえできます！
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// 親しみやすい挨拶をします！
///
/// 呼び出し対象の `Person` に対して "Hello, [name](Person::name)" と言います。
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 のドキュメント
pub mod bar {
/// Bar のドキュメント
pub struct Bar;
}no_inline
別ページや他の場所へのリンクを防ぐために使用されます。
// libcore/prelude からの例
#[doc(no_inline)]
pub use crate::mem::drop;hidden
これを使用すると、rustdoc にこれをドキュメントに含めないよう指示します。
// futures-rs ライブラリからの例
#[doc(hidden)]
pub use self::async_await::*;ドキュメントについては、rustdoc がコミュニティで広く使用されています。これは std ライブラリのドキュメントを生成するために使用されているものです。