# 機能設計書 9-XMLドキュメント生成

## 概要

本ドキュメントは、F#コンパイラのXMLドキュメント生成機能の設計を記述する。XMLドキュメント生成は、F#コード内のドキュメントコメント（///コメント）からXMLドキュメントファイルを生成する機能である。

### 本機能の処理概要

XMLドキュメント生成機能（XmlDocFileWriter）は、F#ソースコード内に記述されたドキュメントコメントを抽出し、.NET標準のXMLドキュメント形式ファイルを生成する。

**業務上の目的・背景**：.NETエコシステムでは、APIドキュメントはXML形式で提供される慣例がある。F#コードに記述されたドキュメントコメントをXMLファイルに出力することで、IntelliSenseでのツールチップ表示、APIリファレンス生成ツール（DocFX等）での利用、NuGetパッケージへの同梱が可能になる。

**機能の利用シーン**：ライブラリ開発時、NuGetパッケージ作成時、APIドキュメント生成時に使用される。--docオプションで出力ファイルを指定。

**主要な処理内容**：
1. 型・メンバーのXMLドキュメント署名（XmlDocSig）計算
2. ドキュメントコメント（XmlDoc）の収集
3. XMLファイル形式での出力

**関連システム・外部連携**：型チェック済みの型付き構文木から情報を抽出。NuGetパッケージ、IntelliSense、DocFXなどと連携。

**権限による制御**：--docオプションで出力有無と出力先を制御。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | ビルドプロパティページ | 主画面 | XMLドキュメント出力設定 |

## 機能種別

ドキュメント生成処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g | TcGlobals | Yes | グローバル型情報 | 初期化済み |
| assemblyName | string | Yes | アセンブリ名 | 有効な名前 |
| generatedCcu | CcuThunk | Yes | 生成されたコンパイル単位 | 型チェック済み |
| xmlFile | string | Yes | 出力XMLファイルパス | .xml拡張子 |

### 入力データソース

- 型チェック済みのCcuThunk

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| xmlDocFile | .xml | XMLドキュメントファイル |

### 出力先

- 指定されたファイルパス

## 処理フロー

### 処理シーケンス

```
1. 署名計算
   ├─ ComputeXmlDocSigs
   │      ├─ doValSig（値の署名）
   │      ├─ doTyconSig（型の署名）
   │      └─ doModuleSig（モジュールの署名）
   └─ XmlDocSig設定

2. XMLファイル書き出し
   ├─ WriteXmlDocFile
   │      ├─ XMLヘッダー出力
   │      ├─ アセンブリ情報出力
   │      └─ メンバー情報出力
   └─ ファイルクローズ
```

### フローチャート

```mermaid
flowchart TD
    A[CcuThunk入力] --> B[ComputeXmlDocSigs]
    B --> C[モジュール走査]
    C --> D[型定義走査]
    D --> E[メンバー走査]
    E --> F[XmlDocSig計算]
    F --> G[WriteXmlDocFile]
    G --> H[XMLヘッダー出力]
    H --> I[メンバー情報出力]
    I --> J[XMLファイル完成]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 拡張子検証 | 出力ファイルは.xml拡張子必須 | 常時 |
| BR-002 | 空ドキュメント | XmlDocが空のメンバーは出力しない | 常時 |
| BR-003 | 署名形式 | .NET標準のXMLドキュメント署名形式 | 常時 |

### 計算ロジック

XmlDocSigは以下の形式で計算：
- 型: `T:Namespace.TypeName`
- メソッド: `M:Namespace.TypeName.MethodName(ParamTypes)`
- プロパティ: `P:Namespace.TypeName.PropertyName`
- フィールド: `F:Namespace.TypeName.FieldName`

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 拡張子エラー | 非.xml拡張子 | .xml拡張子を使用 |

### リトライ仕様

ファイル出力のためリトライは不要。

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

該当なし

## パフォーマンス要件

- XMLドキュメント生成は線形時間で完了

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

特になし

## 備考

XMLドキュメント形式は.NET共通であり、C#やVB.NETと同じ形式。

---

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

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

### 推奨読解順序

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

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

#### Step 2: 署名計算を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | XmlDocFileWriter.fs | `src/Compiler/Driver/XmlDocFileWriter.fs` | ComputeXmlDocSigs関数 |

**主要処理フロー**:
- **15行目**: hasDoc関数 - ドキュメント有無判定
- **17-78行目**: ComputeXmlDocSigs関数 - 署名計算
- **20-22行目**: doValSig - 値の署名設定
- **24-48行目**: doTyconSig - 型の署名設定
- **49-51行目**: doModuleMemberSig - モジュールメンバー署名
- **52-77行目**: doModuleSig - モジュール署名（再帰）

#### Step 3: ファイル出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | XmlDocFileWriter.fs | `src/Compiler/Driver/XmlDocFileWriter.fs` | WriteXmlDocFile関数 |

**主要処理フロー**:
- **80-149行目**: WriteXmlDocFile関数
- **81-82行目**: 拡張子検証
- **86-89行目**: addMember関数 - メンバー追加
- **135-148行目**: XML出力

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

```
WriteXmlDocFile
    │
    ├─ ComputeXmlDocSigs（署名計算）
    │      ├─ doModuleSig（モジュール走査）
    │      │      ├─ doTyconSig（型定義）
    │      │      │      ├─ XmlDocSigOfTycon
    │      │      │      ├─ XmlDocSigOfUnionCase
    │      │      │      └─ XmlDocSigOfProperty
    │      │      │
    │      │      └─ doValSig（値定義）
    │      │             └─ XmlDocSigOfVal
    │      │
    │      └─ doModuleMemberSig
    │             └─ XmlDocSigOfSubModul
    │
    └─ XML出力
           ├─ XMLヘッダー
           ├─ assembly要素
           └─ member要素リスト
```

### データフロー図

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

CcuThunk           ──▶  ComputeXmlDocSigs        ──▶  XmlDocSig設定済みCcu
                              │
                              ▼
型・メンバー        ──▶  ドキュメント収集         ──▶  (id, doc)リスト
                              │
                              ▼
ドキュメントリスト  ──▶  XML出力                 ──▶  .xmlファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| XmlDocFileWriter.fs | `src/Compiler/Driver/XmlDocFileWriter.fs` | ソース | XMLドキュメント生成メイン |
| XmlDoc.fs | `src/Compiler/SyntaxTree/XmlDoc.fs` | ソース | XmlDoc型定義 |
| TypedTreeOps.fs | `src/Compiler/TypedTree/TypedTreeOps.fs` | ソース | XmlDocSig計算関数 |
