Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ドキュメントテスト

Rust プロジェクトをドキュメント化する主な方法は、ソースコードに 注釈を付けることです。ドキュメンテーションコメントは CommonMark Markdown specification で記述され、その中でコードブロックをサポートします。 Rust は正確性を保証するため、これらのコードブロックはコンパイルされ、 ドキュメントテストとして使用されます。

/// 最初の行は、関数を説明する短い要約です。
///
/// 次の行では詳細なドキュメントを提示します。コードブロックは
/// 3 つのバッククォートで始まり、内部に暗黙の `fn main()` と
/// `extern crate <cratename>` を持ちます。`playground` ライブラリ
/// クレートをテストしているか、Playground の Test アクションを使用していると仮定します。
///
/// ```
/// let result = playground::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// 通常、doc コメントには "Examples"、"Panics"、"Failures" セクションを含めることができます。
///
/// 次の関数は 2 つの数値を除算します。
///
/// # Examples
///
/// ```
/// let result = playground::div(10, 2);
/// assert_eq!(result, 5);
/// ```
///
/// # Panics
///
/// 2 番目の引数がゼロの場合、この関数はパニックします。
///
/// ```rust,should_panic
/// // ゼロ除算でパニックする
/// playground::div(10, 0);
/// ```
pub fn div(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("Divide-by-zero error");
    }

    a / b
}

ドキュメント内のコードブロックは、通常の cargo test コマンドを実行すると 自動的にテストされます。

$ cargo test
running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests playground

running 3 tests
test src/lib.rs - add (line 7) ... ok
test src/lib.rs - div (line 21) ... ok
test src/lib.rs - div (line 31) ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

ドキュメントテストの背後にある動機

ドキュメントテストの主な目的は、機能を実行する例として機能することであり、 これは最も重要なガイドラインの 1 つです。 これにより、ドキュメント内の例を完全なコードスニペットとして使用できます。 しかし、? を使用すると、main が unit を返すためコンパイルに失敗します。 ドキュメントから一部のソース行を隠す機能が役に立ちます。 fn try_main() -> Result<(), ErrorType> を書いてそれを隠し、 隠された main でそれを unwrap できます。複雑に聞こえますか？ 次に例を示します。

/// doc テストで隠された `try_main` を使用する。
///
/// ```
/// # // 隠し行は `#` 記号で始まりますが、それでもコンパイル可能です！
/// # fn try_main() -> Result<(), String> { // ドキュメントに表示される本体をラップする行
/// let res = playground::try_div(10, 2)?;
/// # Ok(()) // try_main から返す
/// # }
/// # fn main() { // unwrap() する main の開始
/// #    try_main().unwrap(); // try_main を呼び出して unwrap する
/// #                         // これにより、エラーの場合にテストがパニックします
/// # }
/// ```
pub fn try_div(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err(String::from("Divide-by-zero"))
    } else {
        Ok(a / b)
    }
}

関連項目

  • ドキュメントスタイルに関する RFC505
  • ドキュメントガイドラインに関する API Guidelines