---
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`で警告が出ないか