PricingLoginStart free
Learn Rust Coding · レッスン

ドキュメントテスト

テスト可能な例

レッスン 4/413 ステップ

「ドキュメントテスト」はCoddyKit上の無料Learn Rust Codingレッスンです。 これはレッスン4/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはLearn Rust Coding学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Learn Rust Codingコースには全4レッスンが含まれています。

ドキュメントテストとは

ドキュメントテストは、ドキュメントコメント内のコード例を Cargo が実際にコンパイルして実行する仕組みです。ドキュメントの正しさと、例が動作することを保てます。

ドキュメントコメント内のコード

/// コメント内の # Examples 見出しの下に、フェンス付きコードブロック（3つのバッククォート）でコード例を記述します。デフォルトの言語は Rust です。

/// Doubles a number.
///
/// # Examples
///
///     let result = my_crate::double(4);
///     assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
    n * 2
}

ドキュメントテストの実行

ドキュメントテストは cargo test の一部として実行されます。Doc-tests セクションに分けて報告されます。

cargo test

例でのアサーション

例には通常、アサーションを含めます。これにより、例がコンパイルされるだけでなく、間違っている場合にテストが失敗します。

/// Returns the larger of two values.
///
/// # Examples
///
///     assert_eq!(my_crate::max(3, 7), 7);
///     assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
    if a > b { a } else { b }
}

セットアップ行を非表示にする

行の先頭に # を付けると、その行を実行しつつ、生成されたドキュメントには表示しないようにできます。import などの定型コードに便利です。

/// # Examples
///
///     # use my_crate::Counter;
///     let mut c = Counter::new();
///     c.increment();
///     assert_eq!(c.value(), 1);

疑問符の使用例

? 演算子を使うには、本体を Result を返す非表示の main（またはヘルパー関数）で囲みます。非表示の行は # で始めます。

/// # Examples
///
///     # fn run() -> Result<(), std::num::ParseIntError> {
///     let n: i32 = "42".parse()?;
///     assert_eq!(n, 42);
///     # Ok(())
///     # }

no_run の例

フェンス付きブロックに no_run アノテーションを付けると、コンパイルはしますが実行はしません。ネットワークやファイルが必要な例に便利です。

/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
    format!("contents of {url}")
}

ignore と should_panic

コードフェンスで使えるその他のアノテーション：

  • ignore — コンパイルも実行もしない
  • should_panic — panic が発生することを期待する
  • compile_fail — コンパイルに失敗することを期待する

ドキュメントテストが重要な理由

ドキュメントテストには、次の2つの利点があります。

  • 常に正確なドキュメントを維持できる
  • 公開例のテストカバレッジを追加費用なしで得られる

例が壊れると、テストスイートが失敗します。

例でのクレート名

ドキュメントテストはクレートの外部から実行されるため、クレート名（例：my_crate::func）または use によるインポートを使って項目を参照します。

フェンス付きブロックとインデントブロック

ドキュメントテストでは、次の2種類のブロックを使用できます。

  • 3つのバッククォートを使うフェンス付きブロック。no_run などのアノテーションを指定できます
  • インデントブロック（4つのスペース）。ここでの例ではこちらを使っています

実際のコードでは、フェンス付きブロックのほうが一般的です。

確認問題

ドキュメントテストのコードブロック内で、# から始まる行は何をしますか？

対話的なレッスンで答える

まとめ

ドキュメントテストについて、次のことを学びました。

  • /// ブロック内のコードは cargo test によってコンパイル・実行される
  • アサーションを使って動作を検証する
  • # で準備用の行を生成されたドキュメントから隠せる
  • アノテーションには no_run、ignore、should_panic、compile_fail がある
  • 例を自動的に正しい状態に保てる
無料で開始

AI チューターと学ぶ Rust — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース
39
レッスン
144
無料で学習を始めるコース全体を表示

よくある質問

「ドキュメントテスト」レッスンは無料ですか？

はい。「ドキュメントテスト」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Learn Rust Codingコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Learn Rust Codingコースには全4レッスンが含まれています。

「ドキュメントテスト」で何を学びますか？

テスト可能な例 ブラウザで直接実行するハンズオンコードでLearn Rust Codingを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Learn Rust Codingを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのLearn Rust Codingは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン4/4です。

「ドキュメントテスト」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このLearn Rust Codingレッスンでコードを書いて実行できますか？

はい。すべてのLearn Rust Codingレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. ユニットテスト
  2. 統合テスト
  3. ドキュメントコメント
  4. ドキュメントテスト
← Learn Rust Codingに戻る