# 機能設計書 94-XMLドキュメントパース

## 概要

本ドキュメントは、F#コンパイラにおけるXMLドキュメントコメントの解析機能について記述する。XMLドキュメントコメント（///で始まるコメント）を解析し、IntelliSenseでの表示やXMLドキュメントファイル生成に利用可能な構造化データに変換する。

### 本機能の処理概要

**業務上の目的・背景**：F#はC#と同様にXMLドキュメントコメントをサポートしている。これらのコメントは型、メンバー、パラメータの説明を提供し、IntelliSenseでのヘルプ表示やAPIドキュメント生成に利用される。本機能は、ソースコード内のXMLドキュメントコメントを解析し、構造化されたデータとして抽出する。

**機能の利用シーン**：
- コンパイル時のXMLドキュメントファイル（.xml）生成
- IDEでのIntelliSense表示
- ドキュメント生成ツール（FSharp.Formatting等）での利用
- 型チェック時のパラメータ名取得

**主要な処理内容**：
1. XMLドキュメントコメントの収集 - パース時にトリプルスラッシュコメントを収集
2. XMLの解析 - 収集したテキストをXML形式として解析
3. 要素の抽出 - summary, param, returns, example等の要素を抽出
4. 検証 - XML形式の妥当性を検証し、エラーを報告

**関連システム・外部連携**：レキサーでコメントを認識し、XmlDoc型として構文木に格納。型チェッカーでEntity/Valに関連付けられ、最終的にXMLドキュメントファイルとして出力される。

**権限による制御**：該当なし（コンパイラ内部機能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | IDE統合 | 参照画面 | IntelliSenseでのドキュメント表示 |

## 機能種別

ドキュメント処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| xmlText | string | Yes | XMLドキュメントコメントのテキスト | 有効なXML形式 |
| range | range | Yes | ソースコード上の位置 | - |

### 入力データソース

レキサーが認識したトリプルスラッシュコメント（///）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| XmlDoc | XmlDoc | 解析済みXMLドキュメント |
| unprocessedLines | string list | 未処理の行リスト |
| elaboratedXmlLines | string list | 展開済みのXML行 |

### 出力先

型チェッカー、XMLドキュメントファイル

## 処理フロー

### 処理シーケンス

```
1. コメント収集
   ├─ レキサーがトリプルスラッシュコメントを認識
   └─ 連続するコメント行を結合

2. XML解析
   ├─ コメントテキストをXML形式として解析
   ├─ 不正なXMLの場合はエラーを報告
   └─ 要素と属性を抽出

3. 要素処理
   ├─ <summary>: 概要説明
   ├─ <param name="x">: パラメータ説明
   ├─ <returns>: 戻り値説明
   ├─ <exception>: 例外説明
   └─ <example>: 使用例

4. 出力生成
   ├─ XmlDoc型として構文木に格納
   └─ /doc オプション指定時にXMLファイル生成
```

### フローチャート

```mermaid
flowchart TD
    A[ソースコード] --> B[レキサー]
    B --> C{///コメント?}
    C -->|Yes| D[コメント収集]
    C -->|No| E[通常処理]
    D --> F[連続行結合]
    F --> G[XML解析]
    G --> H{有効なXML?}
    H -->|Yes| I[要素抽出]
    H -->|No| J[エラー報告]
    I --> K[XmlDoc生成]
    K --> L[構文木に格納]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-94-1 | トリプルスラッシュ | ///で始まるコメントのみ処理 | 常時 |
| BR-94-2 | 連続行結合 | 連続するXMLコメント行は結合 | 常時 |
| BR-94-3 | XML検証 | 整形式XMLであることを検証 | 常時 |
| BR-94-4 | 要素継承 | 基底クラスからのドキュメント継承をサポート | <inheritdoc>使用時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FS2001 | InvalidXmlDocComment | XMLが不正 | XMLを修正 |
| FS2002 | MissingParamTag | パラメータのドキュメントなし | <param>を追加 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

XMLドキュメント解析のオーバーヘッドは全体のコンパイル時間の1%未満であること

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

外部XMLファイル参照時のXXE（XML External Entity）攻撃への対策

## 備考

`--warnon:3390`オプションで不正なXMLドキュメントコメントを警告として報告できる。

---

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

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

### 推奨読解順序

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

XMLドキュメントの型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | XmlDoc.fs | `src/Compiler/SyntaxTree/XmlDoc.fs` | XmlDoc型、XmlDocCollector型の定義 |

**主要な型定義**:
- **XmlDoc**: 解析済みXMLドキュメントを表す型
- **XmlDocCollector**: パース中にXMLドキュメントを収集するためのコレクター

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

XMLドキュメント処理の主要な関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | XmlDoc.fs | `src/Compiler/SyntaxTree/XmlDoc.fs` | XmlDocCollector.AddGrabPoint, Process関数 |

**主要処理フロー**:
- **30-50行目**: XmlDocCollector - ドキュメントコメントの収集
- **60-80行目**: XmlDoc.Process - 収集したコメントの処理
- **100-150行目**: XML要素の解析と検証

#### Step 3: 呼び出し元を理解する

XMLドキュメント処理がどこから使われるかを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | lex.fsl | `src/Compiler/lex.fsl` | トリプルスラッシュコメントの認識 |
| 3-2 | pars.fsy | `src/Compiler/pars.fsy` | XmlDocの構文木への格納 |
| 3-3 | CreateILModule.fs | `src/Compiler/CodeGen/CreateILModule.fs` | XMLファイル出力 |

**読解のコツ**:
- XmlDocCollectorはパース中に呼ばれ、GrabPointでコメントを切り取る
- 空のXmlDoc（XmlDoc.Empty）は一般的で、多くの要素がドキュメントを持たない

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

```
lex.fsl
    │ (///コメント認識)
    ▼
pars.fsy
    │ (XmlDocCollector.AddGrabPoint)
    ▼
XmlDoc.fs
    │
    ├─ XmlDocCollector
    │      ├─ AddGrabPoint: コメント収集ポイントの追加
    │      ├─ Process: 収集済みコメントの処理
    │      └─ LinesBefore: 特定位置より前のコメント取得
    │
    └─ XmlDoc
           ├─ Empty: 空のXmlDoc
           ├─ Merge: 複数XmlDocの結合
           └─ UnprocessedLines: 未処理行の取得
```

### データフロー図

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

ソースコード
    │
    ▼
/// <summary>         →  XmlDocCollector  →  XmlDoc型
/// 説明文                   │
/// </summary>               ▼
                      XML解析・検証
                             │
                             ▼
                      ┌──────────────┐
                      │  summary     │
                      │  param       │  →  XMLドキュメントファイル
                      │  returns     │
                      └──────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| XmlDoc.fs | `src/Compiler/SyntaxTree/XmlDoc.fs` | ソース | XMLドキュメント処理の実装 |
| XmlDoc.fsi | `src/Compiler/SyntaxTree/XmlDoc.fsi` | ソース | 公開シグネチャ |
| lex.fsl | `src/Compiler/lex.fsl` | ソース | コメント認識（入力元） |
| pars.fsy | `src/Compiler/pars.fsy` | ソース | XmlDoc収集の呼び出し |
| CreateILModule.fs | `src/Compiler/CodeGen/CreateILModule.fs` | ソース | XMLファイル出力 |
