110 lines
3.0 KiB
Markdown
110 lines
3.0 KiB
Markdown
---
|
||
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`で警告が出ないか
|