llm_worker_rs/.agent/workflows/documentation.md

description
ドキュメントコメントの書き方ガイドライン

ドキュメントコメント スタイルガイド

基本原則

1. 利用者視点で書く: 「何をするものか」「どう使うか」を先に、「なぜそう実装したか」は後に
2. 型パラメータはバッククォートで囲む: Handler<K> ✓ / Handler ✗
3. Examplesはworker::パスで書く: re-export先のパスを使用

構造テンプレート

/// [1行目: 何をするものか - 利用者が最初に知りたいこと]
///
/// [詳細説明: いつ使うか、なぜ使うか、注意点など]
///
/// # Examples
///
/// ```
/// use worker::SomeType;
///
/// let instance = SomeType::new();
/// instance.do_something();
/// ```
///
/// # Notes (オプション)
///
/// 実装上の注意事項や制限があれば記載
pub struct SomeType { ... }

良い例・悪い例

構造体/Trait

// ❌ 悪い例（実装視点）
/// Handler<K>からErasedHandler<K>へのラッパー
/// 各Handlerは独自のScope型を持つため、Timelineで保持するには型消去が必要

// ✅ 良い例（利用者視点）
/// `Handler<K>`を`ErasedHandler<K>`として扱うためのラッパー
///
/// 通常は直接使用せず、`Timeline::on_text_block()`などのメソッド経由で
/// 自動的にラップされます。

メソッド

// ❌ 悪い例（処理内容の説明のみ）
/// ツールを登録する

// ✅ 良い例（何が起きるか、どう使うか）
/// ツールを登録する
///
/// 登録されたツールはLLMからの呼び出しで自動的に実行されます。
/// 同名のツールを登録した場合、後から登録したものが優先されます。
///
/// # Examples
///
/// ```
/// use worker::{Worker, Tool};
///
/// worker.register_tool(MyTool::new());
/// ```

型パラメータ

// ❌ HTMLタグとして解釈されてしまう
/// Handler<K>を保持するフィールド

// ✅ バッククォートで囲む
/// `Handler<K>`を保持するフィールド

ドキュメントの配置

項目	配置場所
型/trait/関数のdoc	定義元のクレート（worker-types等）
モジュールdoc (//!)	各クレートのlib.rsに書く
実装詳細	実装コメント (//) を使用
利用者向けでない内部型	#[doc(hidden)]またはpub(crate)

Examplesのuseパス

re-exportされる型のExamplesでは、最終的な公開パスを使用:

// worker-types/src/tool.rs でも
/// # Examples
/// ```
/// use worker::Tool;  // ✓ worker_types::Tool ではなく
/// ```

チェックリスト

• 1行目は「何をするものか」を利用者視点で説明しているか
• 型パラメータ (<T>, <K> 等) はバッククォートで囲んでいるか
• 主要なpub APIにはExamplesがあるか
• Examplesのuseパスはworker::になっているか
• cargo doc --no-depsで警告が出ないか