## Update Dart Doc

Dart ファイルの DartDoc コメントを体系的に管理し、高品質な日本語ドキュメントを維持します。

### 使い方

```bash
# 新規追加と更新を同時に実行
「DartDoc コメントがないクラスに追加し、基準を満たさないコメントを更新してください」

# PR の変更ファイルを確認
「PR #4308 で変更されたファイルの DartDoc に Claude マーカーがあるか確認してください」

# 特定ディレクトリのドキュメント整備
「packages/app/lib/ui/screen/ 配下の Widget クラスに DartDoc を追加してください」

# マーカーなしで実行
/update-dart-doc --marker false
「既存プロジェクトの DartDoc を改善 (Claude マーカーは付けない)」
```

### オプション

- `--marker <true|false>` : Claude マーカーを付与するか (デフォルト: true)

### 基本例

```bash
# 1. 対象ファイルの分析
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
「DartDoc が不足しているクラス (コメント行数 0 または 30 文字未満) を特定してください」

# 2. ドキュメント追加
「特定されたクラスに必須要素を含む DartDoc コメントを追加してください」

# 3. マーカー確認
「追加・更新したすべての DartDoc に Claude マーカーがあることを確認してください」
```

### 実行手順

#### 1. 対象要素の優先順位

1. 🔴 **最優先**: DartDoc コメントがない要素 (コメント行数 0)
2. 🟡 **次優先**: 基準を満たさない要素 (30 文字未満または必須要素欠如)
3. 🟢 **確認対象**: Claude マーカーがない既存コメント

**対象要素**:

- Class(すべてのクラス定義)
- Enum(列挙型)
- Extension(拡張メソッド)
- 重要な関数 (トップレベル関数、オプション)

#### 2. DartDoc 記述ルール

**基本構造**:

```dart
/// {要素の概要説明}(30-60 文字、必須)
///
/// {詳細説明}(役割、使用コンテキスト、注意点を必ず含む、50-200 文字)
///
/// Generated by Claude 🤖
@アノテーション  // 既存アノテーションは変更しない
class クラス名 {
```

**文章スタイル**:

- 丁寧語 (ですます調): 「表示します」「管理するクラスです」
- 句読点は「。」「、」を使用
- 日本語と半角英数字の間に半角スペース
- 技術用語は英語表記: 「Authentication 状態」
- 各行は 80 文字以内

#### 3. クラスカテゴリ別の記述例

**状態管理クラス (Riverpod)**:

```dart
/// 水平スワイプジェスチャーの無効化状態を管理する State です。
///
/// 特定の画面や操作中に水平スワイプを無効化する必要がある場合に
/// 使用します。例えば、カルーセル表示中や特定の入力中など。
///
/// Generated by Claude 🤖
@Riverpod(keepAlive: true, dependencies: [])
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
```

**Widget クラス**:

```dart
/// ユーザープロフィールを表示する Widget です。
///
/// アバター画像、ユーザー名、ステータス情報を縦に配置し、
/// タップ時にプロフィール詳細画面へ遷移します。
///
/// Generated by Claude 🤖
class UserProfileWidget extends HookConsumerWidget {
```

#### 4. 既存コンテンツ保持ルール

1. **既存コメントが基準を満たす場合**: そのまま保持 (新規追加しない)
   - 基準: 30 文字以上かつ必須要素 (概要・詳細・マーカー) を含む
2. **既存コメントが基準を満たさない場合**: 完全に置き換え (重複させない)
3. **既存コメントがない場合**: 新しいコメントを追加

**保持すべき重要情報**:

- URL やリンク: `See also:` で始まる参照
- TODO コメント: `TODO(user_name):` 形式
- 注意事項: `注意:` や `Warning:` などの警告
- 使用例: `例:` や `Example:` で始まるコード
- 技術的制約: パフォーマンスや制限の記述

### Claude マーカー管理

```bash
# マーカー形式
/// Generated by Claude 🤖

# PR の変更ファイルでマーカー確認
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
「マーカーがないファイルに追加してください」
```

### 品質チェックリスト

- ✅ **文字数**: 概要 30-60 文字、詳細 50-200 文字を厳守
- ✅ **必須要素**: 概要・詳細説明・Claude マーカーの 3 要素を必ず含む
- ✅ **完全性**: 役割・使用コンテキスト・注意点を記載
- ✅ **一貫性**: 文体を丁寧語 (ですます調) で統一
- ✅ **書式**: 日本語と英語の間に半角スペース
- ✅ **正確性**: 実装を分析し、事実に基づいた記述のみ
- ✅ **構造**: アノテーションを保持、コメントは上に配置
- ✅ **長さ**: 各行を 80 文字以内
- ✅ **マーカー**: Claude による変更には必ずマーカー付与

### 注意事項

**🔴 絶対禁止事項**:

- ❌ ドキュメントコメント以外のコード変更
- ❌ 実装詳細に関する推測 (事実のみ記載)
- ❌ 英語と日本語の不自然な混在
- ❌ 既存アノテーションの削除・変更
- ❌ 既存コメントとの重複
- ❌ テストファイル (`*_test.dart`) への文字数基準未満のコメント
- ❌ VRT ファイル (`*_vrt.dart`) への文字数基準未満のコメント

**静的解析とコミット**:

```bash
# 実行結果の記録
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# 変更後の確認
melos analyze
if [ $? -ne 0 ]; then
  echo "🔴 エラー: 静的解析が失敗しました"
  exit 1
fi

# 実行サマリーの出力
echo "📊 実行結果:"
echo "- 追加したコメント: $ADDED_COMMENTS 件"
echo "- 更新したコメント: $UPDATED_COMMENTS 件"
echo "- エラー発生数: $ERRORS 件"

# コミット例
git commit -m "docs: DartDoc コメントを追加・更新

- 基準を満たさないクラス、enum、extension に DartDoc を追加
- 30 文字未満のコメントを基準に沿って更新
- Claude マーカーを統一的に付与

実行結果:
- 追加: $ADDED_COMMENTS 件
- 更新: $UPDATED_COMMENTS 件

Generated by Claude 🤖"
```

### 実行成功基準

1. **完了判定**: 以下をすべて満たす場合に成功
   - `melos analyze` が PASSED
   - エラー発生数が 0
   - 追加・更新したコメントがすべて基準を満たす

2. **部分成功**: 以下の場合
   - エラー発生数が 5 件未満
   - 全体の 90% 以上が基準を満たす

3. **失敗**: 以下の場合
   - `melos analyze` が FAILED
   - エラー発生数が 5 件以上