Apidog

オールインワン協働API開発プラットフォーム

API設計

APIドキュメント

APIデバッグ

APIモック

API自動テスト

Rustdoc: RustにおけるAPIドキュメントの初心者ガイド

中村 拓也

中村 拓也

Updated on 4月 3, 2025

ドキュメントは、開発者とそのコードのユーザーとの架け橋として機能します。Rustのエコシステムでは、ドキュメントはRustdocを通じて第一級の市民に昇格しています。これは、標準のRust配布に付属する高度なドキュメント生成ツールです。他の多くのプログラミング言語のドキュメントツールとは異なり、Rustdocは単なる静的なドキュメントを生成するのではなく、コードの発見性と使いやすさを向上させるインタラクティブでテスト可能なリッチフォーマットのドキュメントウェブサイトを作成します。

Rustの開発者にとって、Apidogはインタラクティブなテスト機能、ビジュアルレスポンスフォーマット、共同作業機能を備えたHTTP APIのための包括的なAPIドキュメント機能を提供します。

ボタン

Apidogはエンドポイント、リクエスト/レスポンスフォーマット、HTTP仕様をドキュメント化することに焦点を当てています。一方、Rustdocは、構造、関数、トレイト、Rustクレートを構成するその他のプログラミング構造のコードを言語レベルでドキュメント化します。両者のシステムは、複雑な技術システムを徹底的、正確かつ使いやすいドキュメントを通じてよりアクセスしやすくするという根本的な目標を共有しています。

ボタン

Rustdocとは何ですか?

Rustdocは、Rustのソースコードと特別なドキュメントコメントを解析して、ブラウジング可能なドキュメントウェブサイトを形成するHTML、CSS、およびJavaScriptファイルを生成するコマンドラインツールです。Rustdocの核心は、コードからドキュメントコメントを抽出し、それを構造化されたドキュメントに変換することによって機能します。

Rustdocの基本操作は次のとおりです:

  1. Rustソースファイルを解析してドキュメントコメントを抽出する
  2. MarkdownからHTMLへのコメントの変換
  3. 検索可能でナビゲート可能なウェブサイト構造の生成
  4. ドキュメントからコード例を抽出し、テストの準備をする
  5. アイテム間の相互参照を作成する
  6. 最終ドキュメントのための静的アセットを生成する

直接呼び出されると、RustdocのバイナリはRustソースファイルを入力として受け取ります:

$ rustdoc src/lib.rs --crate-name my_crate

このコマンドはlib.rsファイルを処理し、デフォルトでdocディレクトリにドキュメントを出力します。ドキュメントはあなたのコードの構造を反映し、モジュール、構造、列挙型、トレイト、その他のRust構造のための別々のページで階層的に構造化されています。

内部では、RustdocはRustコンパイラの内部APIを利用してあなたのコードを解析し、理解します。このコンパイラとの緊密な統合により、Rustdocは正確な相互参照を生成し、型シグネチャを適切に文書化し、コード例が実際にコンパイルされて正しく実行されることを検証します。

Rustにおけるドキュメントコメント

Rustのドキュメントは、通常のコードコメントとは異なる特別なコメント構文に依存しています。主に2種類のドキュメントコメントがあります:

外側のドキュメントコメント(///

外側のドキュメントコメントは、それに続くアイテムをドキュメント化し、3つのスラッシュで示されます:

/// これは以下の関数のドキュメントコメントです。
/// 複数行にわたることができ、Markdownフォーマットをサポートしています。
pub fn documented_function() -> bool {
    true
}

これらのコメントは、コードベース内の関数、構造、列挙型、トレイト、モジュール、その他のアイテムを説明します。これらは、ドキュメント化するアイテムの外に存在するため「外側」のドキュメントと呼ばれます。

内側のドキュメントコメント(//!

内側のドキュメントコメントは、出現するアイテムをドキュメント化し、//!で示されます:

//! このモジュールは構成ファイルを解析するユーティリティを提供します。
/// 
//! # 例
//! 
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // ここに実装
}

内側のドキュメントコメントは、モジュールレベルまたはクレートレベルのドキュメントに一般的に使用されます。lib.rsファイルの先頭に配置されると、全体のクレートをドキュメント化し、生成されたドキュメントのフロントページを形成します。

これらのコメントスタイルの技術的な違いは微妙ですが重要です:///はその後の内容をドキュメント化し、//!はそれを含む内容をドキュメント化します。

RustdocにおけるMarkdownサポート

Rustdocは、いくつかの拡張機能を備えたCommonMark準拠のMarkdownパーサーを使用します。これにより、ドキュメント作成者は豊富なフォーマットオプションにアクセスできます:

基本的なフォーマット

/// # 見出しレベル1
/// ## 見出しレベル2
///
/// 段落は空白行で区切られます。
///
/// *イタリックテキスト* と **太字テキスト** がサポートされています。
///
/// - 順不同リスト
/// - このように作成できます
///
/// 1. 順序付きリスト
/// 2. これも動作します
///
/// `インラインコード` はバックティックで囲まれます。

コードブロック

コードブロックはRustdocで特に重要であり、二重の目的を果たします:ドキュメント内でコード例を表示させ、テストとして抽出することができます。

/// ```rust
/// // これはコードブロックです
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

デフォルトでは、オープニングのトリプルバックティックの後に言語が指定されていない場合、RustdocはコードブロックにRustコードが含まれていると仮定します。ただし、構文ハイライトのために他の言語を指定することもできます:

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

Rustdoc拡張

Rustdocは、いくつかの追加機能を持つCommonMarkを拡張します:

取り消し線テキスト

/// ~~取り消し線のテキスト~~はチルダを使用します。

脚注

/// この文には明確化が必要です[^1].
///
/// [^1]: ここが明確化です。

テーブル

/// | ヘッダー1 | ヘッダー2 |
/// |---------|---------|
/// | セル1   | セル2   |
/// | セル3   | セル4   |

タスクリスト

/// - [x] 完了したタスク
/// - [ ] 未完了のタスク

スマート句読点

Rustdocは自動的にASCII句読点シーケンスをUnicode相当物に変換します:

  • -- はエンダッシュ (–) になります
  • --- はエムダッシュ (—) になります
  • ... は省略記号 (…) になります
  • ストレートクオートはカールクオートになります

詳細なRustdocコマンドラインインターフェース

Rustdocは、ドキュメント生成をカスタマイズするための包括的なコマンドラインオプションを提供します:

$ rustdoc --help

技術的に重要なオプションには以下が含まれます:

  • --document-private-items: デフォルトでは、Rustdocは公開項目のみを文書化します。このフラグは内部文書化に便利なプライベート項目をドキュメントに含めます。
  • --test: ドキュメントの例をテストとして実行し、それらが予想通りにコンパイルされ、実行されることを検証します。
  • --test-args: テストランナーに追加の引数を渡します。たとえば、--nocaptureを指定してテストの出力を表示します。
  • --edition=EDITION: コードを解析し、実行するためのRustのエディションを指定します (2015, 2018, 2021, 2024)。
  • --target=TARGET: 指定したターゲットプラットフォームのドキュメントを生成します。
  • --crate-type=TYPE: テストのためのクレートタイプを指定します (bin、lib、rlib、dylib、cdylib、staticlib、proc-macro)。
  • -L FLAG=PATH: ライブラリの検索パスにディレクトリを追加します。これはテストの依存関係を解決するために重要です。
  • --cfg=SPEC: コンパイラに--cfgフラグを渡し、ドキュメントコード内の条件付きコンパイルを有効にします。
  • --extern NAME=PATH: 外部クレートの位置を指定し、テストが外部依存関係を参照できるようにします。

外部依存関係を持つプロジェクトの場合、通常のRustdoc呼び出しは次のようになります:

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

幸いなことに、Cargoはこの複雑なプロセスを単純なコマンドで自動化します:

$ cargo doc --document-private-items

Cargoとの統合

Cargoは、cargo docコマンドを通じてRustdocを操作するための簡潔なインターフェースを提供します。内部的には、Cargoは適切なパラメータでRustdocを呼び出します:

$ cargo doc --verbose

このコマンドを実行すると、実際のRustdoc呼び出しが表示され、Cargoが依存関係と出力ディレクトリへのパスをどのように構成するかが明らかになります。

コアの機能には以下が含まれます:

  • cargo doc: 現在のクレートとその依存関係のドキュメントを生成します
  • cargo doc --no-deps: 現在のクレートのドキュメントのみを生成します
  • cargo doc --open: ドキュメントを生成し、ウェブブラウザで開きます
  • cargo doc --document-private-items: ドキュメントにプライベートアイテムを含めます
  • cargo test --doc: ドキュメントテストを実行します

Cargoは、Cargo.tomlファイルからクレート名をインテリジェントに決定し、target/doc/の下に正しい出力ディレクトリ構造をセットアップし、すべての依存関係が適切にリンクされることを保証します。

ドキュメントの構造と組織

クレートレベルのドキュメント

クレートレベルのドキュメントは、ライブラリのランディングページとして機能し、包括的な概要を提供する必要があります。これは、lib.rsファイルの最上部にある内側のドキュメント(//!)として書かれます:

//! # 私の高度な暗号ライブラリ
//!
//! このクレートは、次のことに重点を置いた暗号プリミティブを提供します。
//!
//! - **パフォーマンス**: 近代的なCPUに最適化された実装
//! - **セキュリティ**: 形式的に検証されたアルゴリズム
//! - **使いやすさ**: 高水準で使いにくさを軽減するAPI
//!
//! ## クイックスタート
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Secret message";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## 機能
//!
```rust
//! このクレートは以下のアルゴリズムをサポートします。
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

効果的なクレートレベルのドキュメントには、しばしば以下が含まれます:

  1. クレートの目的を簡潔に一文で説明
  2. 主要な概念と機能の詳細な説明
  3. 基本的な使用法を示すクイックスタート例
  4. より複雑なライブラリのためのアーキテクチャの概要
  5. 機能フラグと設定オプション
  6. 互換性情報
  7. パフォーマンス特性

モジュールレベルのドキュメント

モジュールはRustの組織化単位として機能し、その目的や内容を説明する独自のドキュメントを持つべきです:

pub mod symmetric {
    //! 対称暗号アルゴリズム。
    //!
    //! このモジュールは、ブロック暗号とストリーム暗号の実装、
    //! 認証付き暗号アルゴリズム、および関連するユーティリティを提供します。
    //!
    //! # セキュリティ考慮事項
    //!
    //! すべての実装は[セキュリティ会社]によって監査され、
    //! [検証ツール]を使用して形式的に確認されています。

    /// AESブロック暗号の実装で、128、192、および256ビットのキーをサポートします。
    pub struct Aes {
        // ここにフィールド
    }

    // 他のアイテム...
}

アイテムレベルのドキュメント

構造、関数、およびトレイトのような個々のアイテムは、その目的、使用法、特別な考慮事項を説明する焦点を絞ったドキュメントを持つべきです:

/// 暗号学的に安全な乱数生成器。
///
/// このCSPRNGは、暗号操作に適した乱数バイトを生成するために
/// システムのエントロピーソースを使用します。
///
/// # 例
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # セキュリティ
///
/// Linuxでは、利用可能な場合getrandom(2)を使用し、/dev/urandomにフォールバックします。
/// Windowsでは、BCryptGenRandomを使用します。
/// macOSでは、SecRandomCopyBytesを使用します。
pub struct CSPRNG {
    // 実装の詳細
}

impl CSPRNG {
    /// 新しい暗号学的に安全な乱数生成器を作成します。
    ///
    /// # パニック
    ///
    /// システムのエントロピーソースが利用できない場合、パニックが発生します。
    ///
    /// # 例
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // 実装
    }

    /// 指定された数の乱数バイトを生成します。
    ///
    /// # 引数
    ///
    /// * `len` - 生成する乱数バイトの数
    ///
    /// # 戻り値
    ///
    /// `len` 個の暗号学的に安全な乱数バイトを含むベクター。
    ///
    /// # 例
    ///
    /// ```
    /// use crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng_generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // 実装
    }
}

ドキュメントテストの深堀

Rustdocの最も強力な機能の1つは、コード例をテストとして実行できる能力です。これにより、次のことが保証されます:

  1. ドキュメント内の例が実際にコンパイルされる
  2. 例が予想される結果を生成する
  3. 例がAPIの進化に合わせて最新の状態を保つ

ドキュメント内にRustのコードブロックを含めると、Rustdocはそれを抽出し、その周りにテストハーネスを作成します:

/// 2つの数を加えます。
///
/// # 例
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

裏では、Rustdocはこれを次のようなスタンドアロンのテストファイルに変換します:

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

このファイルはコンパイルされて実行されます。プログラムがコンパイルされ、パニックせずに実行される場合、テストは合格します。

テストの前処理

テストを実行する前に、Rustdocはいくつかの変換を適用して、シンプルな例をより使いやすくします:

  1. 一般的な警告(unused_variablesdead_codeなど)は許可されます
  2. 例にextern crateが含まれていない場合、#![doc(test(no_crate_inject))]が指定されていなければ、extern crate <mycrate>;が挿入されます
  3. 例にfn mainが含まれていない場合、コードはfn main() { ... }にラップされます

これらの変換により、ボイラープレートなしで例の重要な部分に集中できます。

テストの動作を制御する

Rustdocは、テストの実行方法を制御するためのいくつかの属性を提供します:

  • ignore: コードはテストされません
  • should_panic: コードはコンパイルされますが、実行時にパニックを起こすべきです
  • compile_fail: コードはコンパイルされるべきではありません
  • no_run: コードはコンパイルされますが、実行されません
  • edition2015, edition2018, edition2021: 特定のRustエディションでコードを実行します

例:

/// ```ignore
/// // このコードはテストされません
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // このコードはパニックを起こすべきです
/// panic!("この例はパニックを示します");
/// ```
///
/// ```compile_fail
/// // このコードはコンパイルされるべきではありません
/// let x: i32 = "これはコンパイルされるべきではない";
/// ```
///
/// ```no_run
/// // このコードはコンパイルされますが実行されません
/// loop {
///     println!("これは永遠に実行されるでしょう!");
/// }
/// ```
///
/// ```edition2021
/// // このコードはRust 2021機能を使用します
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

ドキュメントテストでの?の使用

ドキュメント例はmain()関数でラップされて()を返すため、?演算子を使用するには特別な処理が必要です。2つのアプローチがあります:

  1. Resultを返すmain関数を明示的に定義します:
/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("ファイルの内容: {}", content);
/// # Ok(())
/// # }
/// ```

2. Ok(())で型注釈を使用します:

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("ファイルの内容: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

両方の場合において、いくつかの行の最初の#はレンダリングされたドキュメントからそれらを隠しますが、テストには含まれます。

名前によるアイテムのリンク

Rustdocは、コードベース内の他のアイテムへのリンクを作成するための強力な相互参照システムを提供します。この機能は、ドキュメントのナビゲーション性を大幅に向上させます。

ドキュメント内リンク

別のアイテムへのリンクを作成するには、[item_name]の構文を使用します:

/// 標準ライブラリからの[`HashMap`]型を使用します。
///
/// また、クレート内の他の場所で定義されている[`build_map`]関数も使用します。
pub fn process_data() {
    // 実装
}

/// 事前定義された値で新しい[`HashMap`]を構築します。
pub fn build_map() -> HashMap<String, i32> {
    // 実装
}

Rustdocがこれらのリンクを処理すると、自動的に正しいアイテムに解決され、生成されたHTML内にクリック可能なハイパーリンクが作成されます。

パスの修飾

特に異なるモジュール内で同じ名前を持つアイテムを扱う場合など、より正確なリンクを作成するために、完全修飾パスを使用できます:

/// この関数は、保存のために[`std::collections::HashMap`]を使用し
/// 出力を整形するために[`crate::utils::format`]を使用します。
pub fn complex_operation() {
    // 実装
}

パスの解決はRustの可視性ルールに従い、現在のスコープから可視化できるアイテムのみにリンクできます。

リンクターゲット

さまざまな種類のアイテムにリンクできます:

/// 構造体へのリンク: [`MyStruct`]
/// 列挙体へのリンク: [`Option`]
/// トレイトへのリンク: [`Iterator`]
/// 関数へのリンク: [`process_data`]
/// メソッドへのリンク: [`MyStruct::new`]
/// モジュールへのリンク: [`crate::utils`]
/// 定数へのリンク: [`MAX_SIZE`]
/// 型エイリアスへのリンク: [`Result`]

この包括的なリンクシステムにより、ドキュメント作者は互いに関連するドキュメントのリッチなネットワークを作成し、ユーザーが複雑なAPIをナビゲートできるようにします。

高度なドキュメンテーション機能

ドキュメント属性#[doc]

#[doc]属性は、ドキュメント生成に対する高度な制御を提供します:

// /// コメントを使用することと等しい
#[doc = "以下のアイテムの文書です。"]
pub struct DocumentedStruct;

// ドキュメントからアイテムを隠す
#[doc(hidden)]
pub struct InternalStruct;

// 検索用のエイリアスを追加
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

機能フラグに基づいた条件付き文書用:

/// この関数は驚くべきことを行います。
#[doc = "基本機能の説明。"]
#[cfg_attr(feature = "advanced", doc = "また、「advanced」機能が有効な場合には高度なモードをサポートします。")]
pub fn do_things() {
    // 実装
}

ドキュメントインクルードパターン

異なるドキュメント間でコンテンツを再利用するため:

/// # セーフティ
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // 実装
}

これにより、共通のドキュメントセグメントを別のファイルで管理し、必要な場所でインクルードして重複を減らし、一貫性を確保できます。

スクレイプされた例

Rustdocは、クレートのテストおよび例のディレクトリからコード例を自動的に抽出し、APIの使用に関する追加のコンテキストを提供できます:

$ cargo doc --document-scraped-examples

この機能は、クレート内の公開アイテムの使用をスキャンし、それらの使用を例として抽出することによって機能します。これは、インラインドキュメントの例が不十分な場合がある複雑なAPIにとって特に貴重です。

条件付きドキュメント

cfg属性を使用して、条件に応じてドキュメントを含めたり除外したりできます:

#[cfg(target_os = "windows")]
/// Windows専用の実装詳細。
pub fn windows_only_function() {
    // Windows実装
}

#[cfg(target_os = "linux")]
/// Linux専用の実装詳細。
pub fn linux_only_function() {
    // Linux実装
}

これにより、関連する場合にのみ表示されるプラットフォーム特有または機能特有のドキュメントを作成できます。

ドキュメント内でのカスタムHTML

特別なフォーマットのニーズに対して、Rustdocはドキュメント内にHTMLを直接埋め込むことを許可します:

/// <div class="warning">
/// <strong>警告:</strong> この関数はI/Oを実行し、ブロックする可能性があります。
/// </div>
pub fn blocking_operation() {
    // 実装
}

カスタムCSSと組み合わせることで、Markdown単独では提供できないリッチなフォーマットを可能にします。

カスタムHTMLおよびCSS

Rustdocは、生成されたドキュメントの外観をHTMLおよびCSSを介してカスタマイズすることを許可します:

HTMLの前処理

ドキュメントヘッダーにカスタムHTMLを追加できます:

$ rustdoc src/lib.rs --html-in-header custom-header.html

これは、カスタムスタイルシート、JavaScriptライブラリ、またはメタタグを追加するのに便利です。

CSSのカスタマイズ

ドキュメントにカスタムCSSを適用するには:

$ rustdoc src/lib.rs --css custom-styles.css

CSSファイルはRustdocのHTML構造をターゲットにして、色、フォント、レイアウトなどをカスタマイズできます:

/* メインの背景色を変更 */
body {
    background-color: #f5f5f5;
}

/* 警告ブロックのスタイル */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* コードブロックのカスタムスタイル */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

カスタムレンダリングテーマ

Rustdocは、Light、Rust、Coal、Navy、Ayuなどの複数の組み込みテーマをサポートしています。カスタムテーマを作成することもできます:

$ rustdoc src/lib.rs --theme mytheme.css

ドキュメンテーションのベストプラクティス

技術的な正確さ

ドキュメントは技術的に正確である必要があります。正確な動作、エッジケース、パフォーマンス特性を指定してください:

/// バイナリ検索を使用してソートされたスライス内の要素を検索します。
///
/// # 複雑さ
///
/// 時間の複雑さ: O(log n)
/// 空間の複雑さ: O(1)
///
/// # パニック
///
/// スライスが昇順にソートされていない場合、パニックが発生します。
///
/// # 例
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // 実装
}

構造化されたドキュメント

各種類のアイテムに対して一貫した構造に従うべきです:

関数とメソッド:

  • 簡潔な説明
  • パラメータの説明
  • 戻り値の説明
  • エラーケース
  • パニックセクション(該当する場合)
  • パフォーマンス特性
  • 安全性考慮事項(unsafe関数用)

構造体と列挙型:

  • 目的と高レベルの説明
  • フィールド/バリアントの説明
  • 構成メソッド
  • 一般的な操作
  • 典型的な使用法の例

トレイト:

  • 契約と保証事項
  • 必要なメソッドの説明
  • 提供されるメソッドのドキュメント
  • 実装に関するガイダンス
  • 実装と使用を示す例

言語の正確さ

正確な技術用語を使用し、あいまいさを避けるべきです:

  • 「速い」の代わりに「O(log n)の時間複雑さ」を指定する
  • 「メモリ効率的」の代わりに「定数のスタック領域を使用」を指定する
  • 「失敗する可能性がある」の代わりに正確なエラー条件を指定する
  • 「大きな入力」の代わりに具体的な制限を指定する

バージョン情報

APIの安定性やバージョン管理に関する考慮事項を文書化します:

/// RFC 1234に従ってネットワークパケットを処理します。
///
/// # 安定性
///
/// この関数は0.2.0バージョン以降安定していると見なされます。
///
/// # バージョンの違い
///
/// 0.3.0より前では、この関数は1500バイトを超えるパケットを
/// 静かに切り詰めていました。現在はエラーを返します。
pub fn process_packet(packet: &[u8]) -> Result<ProcessedPacket, PacketError> {
    // 実装
}

高度なテスト手法

異なる環境でのテスト

特定の環境変数で実行するようにドキュメントテストを構成できます:

/// ```
/// # std::env::set_var("API_KEY", "test_key");
/// let client = my_crate::Client::new_from_env()?;
/// # Ok::<(), my_crate::Error>(())
/// ```

外部リソースを使用したテスト

外部リソースが必要なテストは、no_run属性を使用し、要件を説明します:

/// ```no_run
/// // この例はlocalhost:5432のPostgreSQLデータベースを必要とします
/// // ユーザー名「test」とパスワード「test」
/// let db = my_crate::Database::connect(
///     "postgres://test:test@localhost:5432/testdb"
/// )?;
/// # Ok::<(), my_crate::Error>(())
/// ```

エラー処理のテスト

API内でのエラー処理の方法を示します:

/// ```
/// use my_crate::{process_data, DataError};
///
/// // 成功ケース
/// let result = process_data(&[1, 2, 3]);
/// assert!(result.is_ok());
///
/// // エラーケース
/// let error_result = process_data(&[]);
/// assert!(matches!(error_result, Err(DataError::EmptyInput)));
/// ```

国際化とアクセシビリティ

非英語のドキュメント

Rustdocには組み込みの国際