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

## 概要

本ドキュメントは、Lua Language Serverにおけるドキュメント生成機能の設計を記述する。この機能は、LuaDocアノテーションからAPIドキュメントを自動生成し、JSON形式およびMarkdown形式で出力する。

### 本機能の処理概要

**業務上の目的・背景**：Luaプロジェクトの開発者は、コード内のLuaDocアノテーション（@class, @param, @return等）から自動的にAPIドキュメントを生成したい場合がある。手動でのドキュメント作成は時間がかかり、コードとの同期が取れなくなりやすい。本機能はソースコードからドキュメントを自動生成することで、この課題を解決する。

**機能の利用シーン**：
- ライブラリ開発時のAPIドキュメント生成
- プロジェクトの内部ドキュメント自動生成
- 公開APIのリファレンス作成
- 既存ドキュメントの更新

**主要な処理内容**：
1. ワークスペース内のグローバル変数・型の収集
2. 各シンボルのLuaDocアノテーション解析
3. 型情報、フィールド、メソッドの抽出
4. JSON形式（doc.json）およびMarkdown形式（doc.md）での出力
5. カスタムビルドスクリプトによる出力カスタマイズ

**関連システム・外部連携**：
- LuaDoc解析システム
- 型推論システム
- ホバー情報システム（ラベル・説明取得）
- ファイルシステム（出力）

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 34 | ドキュメント出力 | 主画面 | ドキュメントをファイルに出力するコマンド処理 |
| 40 | ドキュメント生成 | 主画面 | ワークスペースからドキュメントを生成するCLI処理 |

## 機能種別

ドキュメント生成 / データ変換処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --doc | string | Yes | ドキュメント生成対象のワークスペースパス | 有効なディレクトリパス |
| --doc_out_path | string | No | 出力先ディレクトリパス | 書き込み可能なパス |
| --doc_update | string | No | 既存ドキュメントの更新パス | 有効なパス |
| outputPath | string | Yes | 出力先パス（makeDoc用） | 書き込み可能なパス |

### 入力データソース

- ワークスペース内のLuaファイル
- LuaDocアノテーション
- カスタムビルドスクリプト（Lua.docScriptPath設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.json | file | JSON形式のAPIドキュメント |
| doc.md | file | Markdown形式のAPIドキュメント |

### 出力先

- 指定された出力ディレクトリ
- カレントディレクトリ（未指定時）

## 処理フロー

### 処理シーケンス

```
1. ワークスペース読み込み
   └─ awaitReadyで完全読み込み待機
2. グローバル収集
   └─ vm.getExportableGlobals()
3. ドキュメントオブジェクト生成
   └─ 各グローバルをdocumentObject()で処理
4. カスタムスクリプト適用
   └─ injectBuildScript()でカスタマイズ
5. シリアライズと出力
   └─ JSON/Markdown形式で保存
```

### フローチャート

```mermaid
flowchart TD
    A[ドキュメント生成開始] --> B[ワークスペース読み込み]
    B --> C[グローバル変数収集]
    C --> D[カスタムスクリプト注入]
    D --> E[各グローバルをドキュメント化]
    E --> F[フィールド・メソッド抽出]
    F --> G[LuaLS設定追加]
    G --> H[ソート]
    H --> I[JSON出力]
    I --> J[Markdown出力]
    J --> K[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | デフォルト出力先 | doc_out_path未指定時はカレントディレクトリ | 未指定時 |
| BR-75-02 | エイリアス展開無効 | ドキュメント生成時はhover.expandAliasをfalseに | 常時 |
| BR-75-03 | 名前順ソート | ドキュメントは名前順にソート | 常時 |
| BR-75-04 | LuaLS設定追加 | doc.jsonにLuaLS設定セクションを追加 | 常時 |

### 計算ロジック

**ドキュメントオブジェクト生成ロジック**:
```lua
-- 各グローバルをドキュメント化
local docs = {}
for i, globalVar in ipairs(globals) do
    table.insert(docs, export.documentObject(globalVar))
end
-- LuaLS設定追加
docs[#docs+1] = export.getLualsConfig()
-- ソート
table.sort(docs, export.sortDoc)
```

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

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

本機能はデータベース操作を行わない。ファイルシステムへの出力のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CLI_CHECK_ERROR_TYPE | 引数型エラー | --docが文字列でない | エラーメッセージ出力 |
| CLI_CHECK_ERROR_URI | URIエラー | 無効なパス指定 | エラーメッセージ出力 |
| - | ファイル書込失敗 | 出力先に書き込めない | エラー配列で返却 |

### リトライ仕様

リトライは行わない。エラー時はエラー情報を返却。

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

トランザクション管理は不要。読み取りと出力のみの処理。

## パフォーマンス要件

- プログレスバーで進捗表示
- 非同期処理で大規模プロジェクトに対応

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

- カスタムビルドスクリプトはLuaコードとして実行されるため、信頼できるソースのみ使用
- ビルドスクリプトには制限された環境でアクセス可能なモジュールのみ提供

## 備考

- Lua.docScriptPath設定でカスタムビルドスクリプトを指定可能
- makeDocObject テーブルの関数をオーバーライドすることで出力をカスタマイズ可能

---

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

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

### 推奨読解順序

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

出力されるドキュメントオブジェクトの構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | export.lua | `script/cli/doc/export.lua` | 14-55行目: docUnionクラスの定義（@class docUnion） |

**読解のコツ**: docUnionは出力されるドキュメントの最も広い型定義。type, name, desc, fields等のフィールドを持つ。

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

CLI呼び出しとランタイム呼び出しの両方を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | init.lua | `script/cli/doc/init.lua` | 176-256行目: runCLI関数 - CLI版エントリ |
| 2-2 | init.lua | `script/cli/doc/init.lua` | 140-173行目: makeDoc関数 - ランタイム版エントリ |

**主要処理フロー**:
1. **176-192行目**: DOCパスとrootUriの解決
2. **210-227行目**: lclientでサーバー初期化
3. **227-242行目**: ドキュメント生成処理
4. **249-254行目**: 結果出力

#### Step 3: グローバル収集を理解する

ドキュメント化対象のグローバル変数収集。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | export.lua | `script/cli/doc/export.lua` | 273-278行目: gatherGlobals関数 |

#### Step 4: ドキュメントオブジェクト生成を理解する

各シンボルのドキュメント化処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | export.lua | `script/cli/doc/export.lua` | 87-123行目: documentObject関数 |
| 4-2 | export.lua | `script/cli/doc/export.lua` | 125-271行目: makeDocObjectテーブル |

**主要処理フロー**:
- **133-147行目**: INIT - 基本情報の抽出
- **149-179行目**: doc.class, doc.field等の処理
- **238-253行目**: type - フィールド収集

#### Step 5: 出力処理を理解する

JSON/Markdown形式での出力。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | export.lua | `script/cli/doc/export.lua` | 305-360行目: serializeAndExport関数 |

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

```
doc.runCLI (公開API - CLI)
    │
    ├─ lclient():start()
    │      └─ サーバー初期化
    │
    └─ injectBuildScript()
           │
           └─ カスタムスクリプト注入

doc.makeDoc (公開API - ランタイム)
    │
    ├─ ws.awaitReady()
    │      └─ ワークスペース読み込み待機
    │
    ├─ injectBuildScript()
    │      └─ カスタムスクリプト注入
    │
    ├─ dirty_export.gatherGlobals()
    │      └─ vm.getExportableGlobals()
    │
    ├─ dirty_export.makeDocs(globals, callback)
    │      │
    │      └─ documentObject(globalVar)
    │             │
    │             ├─ makeDocObject['INIT']
    │             ├─ makeDocObject[type]
    │             └─ 再帰的にフィールド処理
    │
    └─ dirty_export.serializeAndExport(docs, outputPath)
           │
           ├─ jsonb.beautify(docs) → doc.json
           └─ markdown.string() → doc.md
```

### データフロー図

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

Luaファイル ─────────▶ gatherGlobals() ─────────▶ グローバル一覧
                             │
                             ▼
                      documentObject() ─────────▶ ドキュメント
                             │                    オブジェクト
                             ▼
                      serializeAndExport()
                             │
                             ├───────────────────▶ doc.json
                             │
                             └───────────────────▶ doc.md
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| init.lua | `script/cli/doc/init.lua` | ソース | ドキュメント生成のメインモジュール |
| export.lua | `script/cli/doc/export.lua` | ソース | ドキュメントオブジェクト生成・出力 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形出力 |
| markdown.lua | `script/provider/markdown.lua` | ソース | Markdown生成 |
| vm.lua | `script/vm/init.lua` | ソース | グローバル変数取得 |
| hover/description.lua | `script/core/hover/description.lua` | ソース | 説明文取得 |
| hover/label.lua | `script/core/hover/label.lua` | ソース | ラベル取得 |
