docs: Tidying up comments

.agent/workflows/documentation.md

@@ -0,0 +1,109 @@
+---
+description: ドキュメントコメントの書き方ガイドライン
+---
+
+# ドキュメントコメント スタイルガイド
+
+## 基本原則
+
+1. **利用者視点で書く**: 「何をするものか」「どう使うか」を先に、「なぜそう実装したか」は後に
+2. **型パラメータはバッククォートで囲む**: `Handler<K>` ✓ / Handler<K> ✗
+3. **Examplesは`worker::`パスで書く**: re-export先のパスを使用
+
+## 構造テンプレート
+
+```rust
+/// [1行目: 何をするものか - 利用者が最初に知りたいこと]
+///
+/// [詳細説明: いつ使うか、なぜ使うか、注意点など]
+///
+/// # Examples
+///
+/// ```
+/// use worker::SomeType;
+///
+/// let instance = SomeType::new();
+/// instance.do_something();
+/// ```
+///
+/// # Notes (オプション)
+///
+/// 実装上の注意事項や制限があれば記載
+pub struct SomeType { ... }
+```
+
+## 良い例・悪い例
+
+### 構造体/Trait
+
+```rust
+// ❌ 悪い例（実装視点）
+/// Handler<K>からErasedHandler<K>へのラッパー
+/// 各Handlerは独自のScope型を持つため、Timelineで保持するには型消去が必要
+
+// ✅ 良い例（利用者視点）
+/// `Handler<K>`を`ErasedHandler<K>`として扱うためのラッパー
+///
+/// 通常は直接使用せず、`Timeline::on_text_block()`などのメソッド経由で
+/// 自動的にラップされます。
+```
+
+### メソッド
+
+```rust
+// ❌ 悪い例（処理内容の説明のみ）
+/// ツールを登録する
+
+// ✅ 良い例（何が起きるか、どう使うか）
+/// ツールを登録する
+///
+/// 登録されたツールはLLMからの呼び出しで自動的に実行されます。
+/// 同名のツールを登録した場合、後から登録したものが優先されます。
+///
+/// # Examples
+///
+/// ```
+/// use worker::{Worker, Tool};
+///
+/// worker.register_tool(MyTool::new());
+/// ```
+```
+
+### 型パラメータ
+
+```rust
+// ❌ HTMLタグとして解釈されてしまう
+/// Handler<K>を保持するフィールド
+
+// ✅ バッククォートで囲む
+/// `Handler<K>`を保持するフィールド
+```
+
+## ドキュメントの配置
+
+| 項目 | 配置場所 |
+|-----|---------|
+| 型/trait/関数のdoc | 定義元のクレート（worker-types等） |
+| モジュールdoc (`//!`) | 各クレートのlib.rsに書く |
+| 実装詳細 | 実装コメント (`//`) を使用 |
+| 利用者向けでない内部型 | `#[doc(hidden)]`または`pub(crate)` |
+
+## Examplesのuseパス
+
+re-exportされる型のExamplesでは、最終的な公開パスを使用:
+
+```rust
+// 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`で警告が出ないか