ドキュメンテーション

cargo docでtarget/doc上にドキュメンテーションを作ることができます。

cargo testで(ドキュメンテーションテストを含む)すべてのテストを実行でき、さらに cargo test --docでドキュメンテーションテストのみ実行できます。

このコマンドはrustdoc(やrustc)と必要に応じて連携をとります。

Docコメント

Docコメントはドキュメントが必要な巨大プロジェクトに有用です。rustdoc を実行した時、コメントがドキュメントにコンパイルされます。これは///から始まり、Markdownをサポートしています。

#![crate_name = "doc"]

/// 人類を表す
pub struct Person {
    /// ジュリエットがどんなに嫌がろうとも、人は必ず名前を持ちます。
    name: String,
}

impl Person {
    /// 与えられた名前を持つPersonを返す。
    ///
    /// # 引数
    ///
    /// * `name` - 人の名前を保持する文字列
    ///
    /// # 例
    ///
    /// ```
    /// // コメント内のコードは実行できます。
    /// // --testを`rustdoc`に渡すと、テストとして機能します!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// フレンドリーな挨拶!
    ///
    /// `Person`に対して呼び出されたら、"Hello, [name]"と言う。
    pub fn hello(& self) {
        println!("Hello, {}!", self.name);
    }
}

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

    john.hello();
}

テストを実行するためには、コードをライブラリとしてビルドし、テストするライブラリがどこにあるのかrustdocに教えて、それぞれのテストとリンクできるようにする。

$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs

Doc属性

以下は、rustdocで使われる#[doc]属性についての例です。

`inline`

分けられたページへのリンクの代わりにインラインドキュメントを使う。

#[doc(inline)]
pub use bar::Bar;

/// barドキュメント
mod bar {
    /// 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はコミュニティによって広く使われています。これは標準ライブラリのドキュメントにも使われています。

Rust By Example