# 機能設計書 65-コメント操作

## 概要

本ドキュメントは、Prettierのコードフォーマッタにおける「コメント操作」機能の設計を記述する。この機能は、ASTノードにコメントを追加するためのユーティリティ関数群（addLeadingComment、addTrailingComment、addDanglingComment）を提供し、パーサーやプリンターでのコメント処理を支援する。

### 本機能の処理概要

**業務上の目的・背景**：コードフォーマットにおいて、コメントの正確な保持と配置は非常に重要である。パース時にコメントはASTから独立して抽出されるため、フォーマット前に適切なASTノードに関連付ける必要がある。addLeadingComment、addTrailingComment、addDanglingCommentは、コメントの種類に応じて正確にノードに関連付け、フォーマット後も元のコード構造を維持できるようにする。

**機能の利用シーン**：
- パース後のコメント配置（attach-comments処理）
- プラグイン開発でのカスタムコメント処理
- 特殊なコメント配置が必要なケース（装飾子コメント、JSDocコメント等）
- dangling commentの処理（対応するノードがない場合）

**主要な処理内容**：
1. **addLeadingComment**: ノードの前に配置されるコメントを追加
2. **addTrailingComment**: ノードの後に配置されるコメントを追加
3. **addDanglingComment**: どのノードにも直接属さないコメントを追加（オプションのmarker付き）

**関連システム・外部連携**：
- コメントアタッチメントシステム: パース後のコメント配置で使用
- 各言語プリンター: コメント出力時に参照

**権限による制御**：特になし（内部ユーティリティ関数）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Misc - Technical Details | 補助機能 | コメント操作の技術的詳細を説明 |

## 機能種別

データ操作 / ユーティリティ

## 入力仕様

### 入力パラメータ

#### addLeadingComment

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| node | object | Yes | コメントを追加するASTノード | - |
| comment | object | Yes | 追加するコメントオブジェクト | - |

#### addTrailingComment

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| node | object | Yes | コメントを追加するASTノード | - |
| comment | object | Yes | 追加するコメントオブジェクト | - |

#### addDanglingComment

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| node | object | Yes | コメントを追加するASTノード | - |
| comment | object | Yes | 追加するコメントオブジェクト | - |
| marker | any | No | コメントの識別マーカー | - |

### 入力データソース

- パース処理で抽出されたコメント
- カスタムプラグインからの呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし、ノードを直接変更 |

### 出力先

- 入力されたASTノードのcommentsプロパティが変更される

## 処理フロー

### 処理シーケンス

#### 共通処理（addCommentHelper）

```
1. ノードのcommentsプロパティを取得（なければ空配列を作成）
2. コメントをcommentsに追加
3. comment.printedをfalseに設定
4. comment.nodeDescriptionにノード情報を設定
```

#### addLeadingComment

```
1. comment.leadingをtrueに設定
2. comment.trailingをfalseに設定
3. addCommentHelperを呼び出し
```

#### addTrailingComment

```
1. comment.leadingをfalseに設定
2. comment.trailingをtrueに設定
3. addCommentHelperを呼び出し
```

#### addDanglingComment

```
1. comment.leadingをfalseに設定
2. comment.trailingをfalseに設定
3. markerが指定されていればcomment.markerに設定
4. addCommentHelperを呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{関数種別}
    B -->|addLeadingComment| C[leading=true, trailing=false]
    B -->|addTrailingComment| D[leading=false, trailing=true]
    B -->|addDanglingComment| E[leading=false, trailing=false]
    E --> F{markerあり?}
    F -->|Yes| G[comment.marker = marker]
    F -->|No| H[addCommentHelper]
    C --> H
    D --> H
    G --> H
    H --> I[node.comments取得/作成]
    I --> J[comments.push comment]
    J --> K[comment.printed = false]
    K --> L[comment.nodeDescription設定]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-65-01 | コメント配列の遅延初期化 | commentsプロパティは初回アクセス時に作成 | ノードにcommentsがない場合 |
| BR-65-02 | 印刷フラグの初期化 | printedフラグは常にfalseで初期化 | すべてのコメント追加時 |
| BR-65-03 | leadingとtrailingの排他性 | leadingとtrailingは同時にtrueにならない | 設計上の制約 |
| BR-65-04 | danglingの識別 | leading=false かつ trailing=false がdangling | 分類ロジック |

### 計算ロジック

describeNodeForDebugging関数によるノード説明の生成:
```
nodeDescription = nodeType + (nodeName ? " " + nodeName : "")
  - nodeType: node.type || node.kind || "(unknown type)"
  - nodeName: node.name || node.id.name || node.key.name || node.value || node.operator
  - nodeName は20文字を超える場合は切り詰める
```

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を伴わない。

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本機能では例外を発生させない | - |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし（データベース操作なし）

## パフォーマンス要件

- O(1)の処理時間でコメントを追加
- ノードのcommentsプロパティへの直接変更のため、追加のメモリ割り当ては最小限

## セキュリティ考慮事項

- 特別なセキュリティ要件なし
- 入力ノードを直接変更するため、呼び出し元での副作用に注意

## 備考

- これらの関数はプラグイン開発者向けにutilモジュールから公開されている
- コメントのアタッチメントロジックはattach-comments.jsで実装されている

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

コメントオブジェクトの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | utilities.js | `src/main/comments/utilities.js` | コメントに設定されるプロパティ |

**読解のコツ**: コメントオブジェクトには以下のプロパティが設定される:
- `leading`: boolean - 先行コメントかどうか
- `trailing`: boolean - 後続コメントかどうか
- `printed`: boolean - 出力済みかどうか
- `nodeDescription`: string - デバッグ用ノード説明
- `marker`: any - dangling commentの識別子（オプション）

#### Step 2: エントリーポイントを理解する

公開APIとしてのエクスポート構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | public.js | `src/utilities/public.js` | エクスポート定義 |

**主要処理フロー**:
- **137-140行目**: addDanglingComment、addLeadingComment、addTrailingCommentのエクスポート

#### Step 3: 実装詳細を理解する

コメント追加のロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utilities.js | `src/main/comments/utilities.js` | メイン実装 |

**主要処理フロー**:
- **1-16行目**: describeNodeForDebugging - ノード説明の生成
- **18-23行目**: addCommentHelper - 共通処理
- **25-29行目**: addLeadingComment
- **31-38行目**: addDanglingComment
- **40-44行目**: addTrailingComment

### プログラム呼び出し階層図

```
addLeadingComment (utilities.js)
    │
    └─ addCommentHelper (utilities.js)
           │
           └─ describeNodeForDebugging (utilities.js)

addTrailingComment (utilities.js)
    │
    └─ addCommentHelper (utilities.js)
           │
           └─ describeNodeForDebugging (utilities.js)

addDanglingComment (utilities.js)
    │
    └─ addCommentHelper (utilities.js)
           │
           └─ describeNodeForDebugging (utilities.js)
```

### データフロー図

```
[入力]                    [処理]                           [出力]

node ─────────────────▶ 関数呼び出し ───────────────────▶ (void)
comment                     │                                 │
marker (optional)           ▼                                 │
                       comment.leading設定                    │
                            │                                 │
                            ▼                                 │
                       comment.trailing設定                   │
                            │                                 │
                            ▼                                 │
                       comment.marker設定 (optional)          │
                            │                                 │
                            ▼                                 │
                       addCommentHelper                       │
                            │                                 │
                            ├── node.comments取得/作成        │
                            │                                 │
                            ├── comments.push(comment)        │
                            │                                 │
                            ├── comment.printed = false       │
                            │                                 │
                            └── comment.nodeDescription設定 ──▶ node.comments変更済み
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| utilities.js | `src/main/comments/utilities.js` | ソース | コメント操作関数の実装 |
| public.js | `src/utilities/public.js` | ソース | 公開エクスポート |
| index.js | `src/index.js` | ソース | API公開（util経由） |
| attach-comments.js | `src/main/comments/attach-comments.js` | ソース | コメントアタッチメント（使用例） |
