# 画面設計書 40-ドキュメント生成

## 概要

本ドキュメントは、Lua Language ServerのCLIコマンド「ドキュメント生成（--doc）」の画面設計書です。

### 本画面の処理概要

この画面（CLIコマンド）は、Luaワークスペースからドキュメントを生成してファイルに出力する機能を提供します。

**業務上の目的・背景**：
Luaプロジェクトの開発者は、コード内のLuaDocアノテーションや型情報から自動的にAPIドキュメントを生成したい場合があります。本コマンドは、Language Serverの解析機能を活用して、プロジェクト内のグローバル変数、クラス、関数などの情報を抽出し、JSON形式とMarkdown形式のドキュメントファイルを生成します。これにより、手動でのドキュメント作成の手間を削減し、コードと同期した最新のドキュメントを維持できます。

**画面へのアクセス方法**：
本コマンドは、以下の方法でトリガーされます：
- コマンドラインで `lua-language-server --doc=<workspace_path>` を実行

**主要な操作・処理内容**：
1. ワークスペースパスを解決
2. 設定ファイル（.luarc.doc.json）のパスを処理
3. LSPクライアントエミュレータを初期化
4. ワークスペースの準備完了を待機
5. カスタムビルドスクリプトをインジェクション
6. グローバル変数を収集
7. ドキュメントオブジェクトを構築
8. JSON/Markdown形式でシリアライズして出力

**画面遷移**：
- 入力元：コマンドライン起動
- 出力先：ファイル出力（doc.json, doc.md）

**権限による表示制御**：
特別な権限制御はありません。出力先ディレクトリへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 75 | ドキュメント生成 | 主機能 | ワークスペースからドキュメントを生成するCLI処理 |
| 17 | ホバー情報 (textDocument/hover) | 補助機能 | ドキュメント生成時のホバー情報取得 |
| 55 | LuaDoc解析 | 補助機能 | アノテーションからドキュメント情報を抽出 |

## 画面種別

CLI（コマンドライン出力）

## URL/ルーティング

- CLIオプション: `--doc=<workspace_path>`
- ハンドラファイル: `script/cli/doc/init.lua`
- 関連オプション:
  - `--doc_out_path`: ドキュメント出力先パス
  - `--doc_update`: 既存ドキュメントの更新
  - `--configpath`: 設定ファイルパス

## 入出力項目

### 入力パラメータ

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| --doc | string | Yes | ドキュメント生成対象ワークスペースのパス |
| --doc_out_path | string | No | ドキュメント出力先パス（デフォルト: カレントディレクトリ） |
| --doc_update | string | No | 既存ドキュメント（doc.json）のパス |
| --configpath | string | No | 設定ファイルパス |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| file | JSON | doc.json - JSON形式ドキュメント |
| file | Markdown | doc.md - Markdown形式ドキュメント |
| stdout | text | 進捗表示と完了メッセージ |

## 表示項目

### 進捗表示

| 項目名 | 表示内容 |
|--------|---------|
| 初期化メッセージ | CLI_DOC_INITING |
| プログレスバー | `>>>>>>>>>>>========= 0123/0456` |

### 完了表示

| 項目名 | 表示内容 |
|--------|---------|
| 完了メッセージ | CLI_DOC_DONE |
| 出力ファイル | 生成されたファイルパス一覧 |

## イベント仕様

### 1-ドキュメント生成実行

1. **言語設定**: lang(LOCALE)で言語を設定
2. **DOC_UPDATE処理**: 既存doc.jsonからDOC_OUT_PATH, DOCを取得
3. **パラメータ検証**: DOCの型確認
4. **URI変換**: furi.encode()でrootUriを生成
5. **設定パス処理**: CONFIGPATHがある場合、luarcParentUriを設定
6. **LSPクライアント起動**: lclient():start()
7. **クライアント初期化**: client:initialize()
8. **診断無効化**: config.set('Lua.diagnostics.enable', false)
9. **ワークスペース準備待機**: ws.awaitReady()
10. **ビルドスクリプトインジェクション**: injectBuildScript()
11. **グローバル収集**: export.gatherGlobals()
12. **ドキュメント構築**: export.makeDocs()
13. **進捗表示**: 定期的に進捗を更新
14. **出力先解決**: DOC_OUT_PATHまたはカレントディレクトリ
15. **シリアライズ・出力**: export.serializeAndExport()
16. **完了メッセージ**: 出力ファイルパスを表示

## データベース更新仕様

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

本機能はデータベースを使用しませんが、以下のファイルへの影響があります：

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| ドキュメント出力 | doc.json | CREATE/UPDATE | JSON形式ドキュメントを出力 |
| ドキュメント出力 | doc.md | CREATE/UPDATE | Markdown形式ドキュメントを出力 |

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|---------|--------------|
| CLI_DOC_INITING | Info | 初期化中 | 初期化中メッセージ |
| CLI_DOC_DONE | Info | 出力完了時 | 完了メッセージ |
| CLI_CHECK_ERROR_TYPE | Error | パラメータ型エラー | 型エラーメッセージ |
| CLI_CHECK_ERROR_URI | Error | URI解決失敗 | URIエラーメッセージ |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| DOCが文字列でない | エラーメッセージを表示して終了 |
| URI解決失敗 | エラーメッセージを表示して終了 |
| doc.json読み込み失敗（--doc_update時） | エラーをスロー |
| ビルドスクリプト読み込み失敗 | エラーをスロー |
| ファイル書き込み失敗 | エラーをスロー |

## 備考

- カスタムビルドスクリプト（Lua.docScriptPath）を使用して出力をカスタマイズできます
- ビルドスクリプトはexportモジュールのクローンを受け取り、関数をオーバーライドできます
- --doc_updateを使用すると、既存のdoc.jsonからDOCパスを読み取って更新します
- 診断は無効化され、hover.expandAliasもfalseに設定されます
- 進捗表示は0.2秒間隔で更新されます

---

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

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

### 推奨読解順序

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

まず、ドキュメント生成で使用されるデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | export.lua | `script/cli/doc/export.lua` | docUnion型の定義（37-55行目）を理解 |
| 1-2 | export.lua | `script/cli/doc/export.lua` | doctype列挙（14-35行目）を理解 |

**読解のコツ**: `docUnion`はドキュメント要素の汎用型で、type, name, desc, fields, defines, args, returnsなど多くのフィールドを持ちます。

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

コマンドの起点を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | init.lua | `script/cli/doc/init.lua` | runCLI関数（176-256行目） |

**主要処理フロー**:
1. **177行目**: 言語設定
2. **179-181行目**: DOC_UPDATE処理
3. **183-186行目**: パラメータ検証
4. **188-192行目**: URI変換
5. **210-243行目**: LSPクライアントでのドキュメント生成

#### Step 3: ビルドスクリプトインジェクションを理解する

injectBuildScript()の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | init.lua | `script/cli/doc/init.lua` | injectBuildScript関数（106-138行目） |

**主要処理フロー**:
- **107行目**: Lua.docScriptPath設定を取得
- **108行目**: exportモジュールをクローン
- **113-131行目**: ビルドスクリプトを読み込んで実行
- **137行目**: 変更されたモジュールを返す

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

gatherGlobals()の実装を確認します。

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

**主要処理フロー**:
- **277行目**: vm.getExportableGlobals()でエクスポート対象を取得

#### Step 5: ドキュメント構築を理解する

makeDocs()とdocumentObject()の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | export.lua | `script/cli/doc/export.lua` | makeDocs関数（284-293行目） |
| 5-2 | export.lua | `script/cli/doc/export.lua` | documentObject関数（92-123行目） |

**主要処理フロー**:
- **285-289行目**: 各グローバルに対してdocumentObject()を呼び出し
- **92-123行目**: 再帰的にドキュメントオブジェクトを構築

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

```
lua-language-server --doc=<path>
    │
    └─ doc/init.lua:runCLI()
           │
           ├─ getPathDocUpdate() [--doc_update時]
           │      └─ findDocJson()
           │
           ├─ furi.encode()
           │
           ├─ lclient():start()
           │      │
           │      └─ client:registerFakers()
           │
           ├─ client:initialize()
           │
           ├─ config.set('diagnostics.enable', false)
           │
           ├─ ws.awaitReady()
           │
           ├─ injectBuildScript()
           │      │
           │      ├─ reinstantiateModule()
           │      │
           │      └─ loadfile(docScriptPath)
           │
           ├─ export.gatherGlobals()
           │      │
           │      └─ vm.getExportableGlobals()
           │
           ├─ export.makeDocs()
           │      │
           │      └─ export.documentObject()
           │             │
           │             ├─ makeDocObject['INIT']
           │             │
           │             └─ makeDocObject[type]
           │
           └─ export.serializeAndExport()
                  │
                  ├─ jsonb.beautify()
                  │
                  └─ markdown()
```

### データフロー図

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

--doc=<path> ───▶ doc/init.lua:runCLI() ───▶ ファイル出力
                        │
                        ▼
                  URI変換
                        │
                        ▼
                  lclient初期化
                        │
                        ▼
                  ws.awaitReady()
                        │
                        ▼
                  injectBuildScript()
                        │
                        ▼
                  dirty_export (カスタマイズ済みモジュール)
                        │
                        ▼
                  gatherGlobals()
                        │
                        ▼
                  vm.global[] (グローバル一覧)
                        │
                        ▼
                  makeDocs()
                        │
                        ▼
                  docUnion[] (ドキュメントオブジェクト)
                        │
                        ▼
                  serializeAndExport()
                        │
                   ┌────┴────┐
                   ▼         ▼
              doc.json    doc.md
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| init.lua | `script/cli/doc/init.lua` | ソース | CLIエントリーポイント、makeDoc関数 |
| export.lua | `script/cli/doc/export.lua` | ソース | ドキュメントオブジェクト構築、シリアライズ |
| lclient.lua | `script/lclient.lua` | ソース | LSPクライアントエミュレータ |
| vm.lua | `script/vm.lua` | ソース | グローバル収集 |
| workspace.lua | `script/workspace/workspace.lua` | ソース | ワークスペース管理 |
| config.lua | `script/config/config.lua` | ソース | 設定管理 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形 |
| markdown.lua | `script/provider/markdown.lua` | ソース | Markdown生成 |
| file-uri.lua | `script/file-uri.lua` | ソース | URIエンコード/デコード |
