rust-documentation

Rust のドキュメント

ドキュメントは実行可能なインターフェースとして扱います。API リファレンスはコードの近くに置き、概念ガイドや運用ガイドは適切なブックまたはリポジトリ内のドキュメントにまとめ、サンプルはサポート対象の API に対してコンパイルします。

対象範囲と振り分け

rustdoc コメント、クレートおよびモジュールのドキュメント、ドクテスト、ドキュメント内リンク、README の生成、mdBook、docs.rs の設定、リンクチェック、スペルチェック、ドキュメントのリリースゲートには、このスキルを使用します。

一般的なテストアーキテクチャは rust-testing、公開 API の互換性は rust-code-review、Cargo のメタデータと公開は rust-cargo-build、API の形状やトレイト設計の判断は rust-api-design、Rust 以外のオフィス文書形式は専用のドキュメントスキルに振り分けます。このスキルでは、すでに存在するものをドキュメント化します。API をどう設計するかは rust-api-design が判断します。

ワークフロー

1. 読者とドキュメントの公開先を特定する

公開クレート、バイナリ、機能、ターゲット、サンプル、README、ブック、生成されたリファレンス、ホストされた出力を一覧にします。各公開先の対象読者と担当者を定義します。

公開先	主な目的
クレートおよびモジュールのドキュメント	導入経路、アーキテクチャ、機能とプラットフォームの概要
項目のドキュメント	契約、エラー、パニック、安全性、サンプル、計算量
ドクテストとサンプル	実行可能な使用方法と互換性の証明
README	見つけやすさ、インストール、最小限のクイックスタート、サポートポリシー
mdBook	チュートリアル、概念、運用、移行、長文ガイド
docs.rs	バージョン管理された公開 API の公開

情報源を明示せずに、同じ文章を複数の公開先で重複させないようにします。

2. 契約をドキュメント化する

各公開 API について、該当する項目だけをドキュメント化します。

• 項目の動作と重要な意味上の仕様
• アサーションと現実的なインポートを含む # Examples
• 意味のある失敗カテゴリごとの # Errors
• 到達可能なパニック条件を示す # Panics
• unsafe API における呼び出し側の義務を示す # Safety
• キャンセル、ブロッキング、メモリ確保、計算量、プラットフォーム、機能、MSRV の制約

壊れやすい手書き URL より、[`Client::send`] のようなドキュメント内リンクを優先します。クレートの境界でリンク切れチェックを有効にします。

#![deny(rustdoc::broken_intra_doc_links)]

missing_docs は意図的に採用します。どの公開互換性サーフェスにドキュメントが必要かを決める前に、グローバルでは有効にしないでください。

Rust API ガイドライン — ドキュメント規則

Rust API ガイドラインでは、高品質なクレートが満たすべき 5 つのドキュメント規則（C-DOC、C-DOC-COMMENT、C-META、C-EXAMPLE、C-LINK）が定義されています。あらゆる公開クレートのドキュメントにおける合格基準として扱ってください。詳細な理由、アンチパターン、具体例はAPI ガイドライン — ドキュメントにあります。このセクションは振り分けの概要です。

C-DOC — すべての項目をドキュメント化する

すべての公開項目（関数、構造体、列挙型、トレイト、モジュールなど）にドキュメントコメントを付けます。missing_docs lint で機械的に強制します。

// src/lib.rs
#![deny(missing_docs)]

適用範囲は慎重に決めます。クレートルートでの #![deny(missing_docs)] が最も厳格なポリシーです。封印されたモジュール、生成コード、意図的に不安定な API など、一部の公開先で例外が必要な場合は、可能な限り小さな項目に #[allow(missing_docs)] を指定し、その理由を記録します。

C-DOC-COMMENT — /// と //!

• /// は次の項目（関数、構造体、フィールド、またはその下で名前を付けて宣言されたモジュール）をドキュメント化します。
• //! は現在のモジュールまたはクレートをドキュメント化します（ファイルの先頭、またはモジュール本体の内部に配置します）。
• どちらも Markdown をレンダリングし、ドキュメント内リンク [Foo] をサポートします。

src/lib.rs の先頭、および概要が必要な各モジュールのルートでは //! を使用します。ドキュメント化するすべての項目には /// を使用します。

C-META — クレートレベルのドキュメントで必須事項を網羅する

src/lib.rs の冒頭には、次の内容を網羅した //! ドキュメントを記述します。

• クレートの機能と、使用例へのリンク。
• 始め方（セットアップ／統合ドキュメント、またはクイックスタートへのリンク）。
• 各機能フラグと、それぞれで有効になる機能。
• 最小サポート Rust バージョン（MSRV）。
• ライセンス。慣例的にはデュアルライセンスの MIT OR Apache-2.0。

cargo doc --no-deps -p <crate> を実行し、クレートのランディングページがモジュール一覧だけでなく、それ単体で内容を把握できる概要になっていることを確認します。

C-EXAMPLE — # Examples を含む実行可能な例

すべての公開アイテムに # Examples セクションを設けます。例はコンパイルでき、ドックテストとして実行できるようにします。フェンスの属性は正確に選択してください。

• 属性なし — コンパイルして実行します。
• ```no_run — コンパイルしますが、実行はスキップします（ネットワーク、ファイル、ハードウェア）。
• ```ignore — 完全にスキップします。理由を記載してください。
• ```compile_fail — 拒否される入力例の提示には、proc-macro クレートでのみ使用します。

壊れた例を隠すために no_run を使わないでください。ワークフローでファイルや認証情報が必要な場合は examples/ に移し、実際のターゲットとしてテストします。

C-LINK — ドキュメント内リンク

[ItemType] および [ItemType::method] の構文を使い、rustdoc がリンク先を解決し、名前変更を追跡できるようにします。同じクレート内の型へのパスを手書きしないでください。クレートの境界で、壊れたリンクの検出を有効にします。

#![deny(rustdoc::broken_intra_doc_links)]

各ルールの詳細な例、アンチパターン、lint の一覧、検証コマンドについては、API ガイドライン — ドキュメントをお読みください。

3. 例を実行可能にする

小規模な公開 API の契約にはドックテストを使い、ワークフロー全体には examples/ クレートを使います。フェンスは正確に指定してください。

• 通常の Rust フェンスはコンパイルして実行します。
• no_run は、利用できない外部への作用を必要とするコードをコンパイルします。
• compile_fail は、完全な診断内容に依存せずに、不適切な使い方が拒否されることを示します。
• ignore は最終手段とし、理由を記載します。

次を実行します。

cargo test --workspace --doc --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps

API ドキュメントを作成する際は、rustdoc とドックテストをお読みください。

4. mdBook で詳細なガイドを作成する

API ドキュメントに詰め込みすぎないよう、チュートリアル、アーキテクチャ、運用、移行に関する資料には mdBook を使います。SUMMARY.md は、明示的なナビゲーションの定義として維持します。Rust コードサンプルは mdbook test でテストし、CI でビルドして、内部リンクと外部リンクを確認します。mdBook とプロジェクトガイドをお読みください。

5. バージョン管理された公開に備える

パッケージのメタデータ、docs.rs のターゲットと機能の設定、README のリンク、リポジトリの URL、ライセンス、例、非公開／プライベート API を確認します。作成者のマシンだけでなく、ロックされた依存関係グラフと、サポート対象の MSRV／現行安定版を使ってドキュメントを検証します。

許可なく公開したり、ホストされたドキュメントを変更したり、外部分析機能を有効にしたりしないでください。ドキュメントリリースの品質をお読みください。

品質ゲート

cargo fmt --all --check
cargo test --workspace --doc --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
mdbook test path/to/book
mdbook build path/to/book
lychee README.md docs book/src
typos README.md docs book/src src

プロジェクトに存在するツール、またはインストールが承認されたツールのみを実行します。Rust 以外のドキュメントツールは CI でバージョンを固定し、チェック専用ジョブで文章を黙って書き換えないでください。

完了条件

• 対象読者ごとに明確な入り口を用意し、情報源が矛盾しないようにします。
• 該当する場合は、公開エラー、パニック、安全性、機能、ターゲット、互換性をドキュメントに記載します。
• 代表的なドキュメントの例をコンパイルして実行します。
• 壊れたドキュメント内リンクとリポジトリリンクを検出します。
• 公開を予定しているものと同じ機能およびターゲットでドキュメントをビルドします。
• スキップした外部、プラットフォーム、ホスト環境での検証を明記します。

リソース

• rustdoc とドックテスト
• mdBook とプロジェクトガイド
• ドキュメントリリースの品質
• API ガイドライン — ドキュメント
• 実行シナリオ
• examples/golden-docs/：ドキュメント内リンクとドックテストが強制される、コンパイル可能なクレート。

アップストリームの情報源

• The rustdoc Book
• Rustdoc documentation tests
• Cargo doc
• mdBook
• docs.rs metadata
• Rust API Guidelines — Documentation

データプライバシー

このスキルは、ユーザーデータを収集、保存、送信しません。公開前に、例、生成されたソースリンク、ビルドログ、ホスト型分析に秘密情報や独自のパスが含まれていないか確認してください。