# 画面設計書 34-ドキュメント出力

## 概要

本ドキュメントは、Lua Language ServerのLSPコマンド「ドキュメント出力（lua.exportDocument）」の画面設計書です。

### 本画面の処理概要

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

**業務上の目的・背景**：
開発者がLuaプロジェクトのAPIドキュメントを生成したい場合、本コマンドを使用することで、Language Serverが解析した型情報やLuaDocアノテーションに基づいたドキュメントをJSON形式およびMarkdown形式で出力できます。これにより、プロジェクトのドキュメンテーション作業を効率化し、常に最新のコードに基づいたドキュメントを維持できます。CLIモードとは異なり、エディタ上から対話的にドキュメント生成を実行できます。

**画面へのアクセス方法**：
本コマンドは、以下の方法でトリガーされます：
- LSPクライアントからの `workspace/executeCommand` リクエストで `lua.exportDocument` コマンドを実行
- VS Codeのコマンドパレットから「Lua: Export Document」を選択

**主要な操作・処理内容**：
1. 出力パスを引数から取得（未指定時はLOGPATH）
2. cli.doc.makeDoc()を呼び出してドキュメント生成
3. グローバル変数を収集
4. ドキュメントオブジェクトを構築
5. JSON/Markdown形式でシリアライズして出力
6. 完了メッセージをクライアントに表示

**画面遷移**：
- 入力元：コマンドパレット、LSPクライアント
- 出力先：ファイル出力後、完了メッセージを表示

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 75 | ドキュメント生成 | 主機能 | ドキュメントをファイルに出力するコマンド処理 |

## 画面種別

LSPコマンド（非同期処理）

## URL/ルーティング

- LSPコマンド名: `lua.exportDocument`
- プロトコル: `workspace/executeCommand`
- ハンドラファイル: `script/core/command/exportDocument.lua`

## 入出力項目

### 入力パラメータ

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| args | table | No | コマンド引数の配列 |
| args[1] | string | No | 出力パスのURI（省略時はLOGPATH） |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (ファイル出力) | file | doc.json - JSON形式ドキュメント |
| (ファイル出力) | file | doc.md - Markdown形式ドキュメント |

## 表示項目

完了時に表示されるメッセージ：

| 項目名 | 表示内容 |
|--------|---------|
| 完了メッセージ | CLI_DOC_DONE |
| 出力ファイル1 | doc.jsonへのリンク |
| 出力ファイル2 | doc.mdへのリンク |

## イベント仕様

### 1-ドキュメント出力実行

1. **リクエスト受信**: コマンドパラメータを受信
2. **出力パス解決**: args[1]をURIデコードするか、LOGPATHを使用
3. **ドキュメント生成**: doc.makeDoc(outputPath)を呼び出し
4. **ワークスペース準備待機**: ws.awaitReady()で準備完了を待機
5. **グローバル収集**: export.gatherGlobals()でエクスポート対象を収集
6. **ドキュメント構築**: export.makeDocs()でドキュメントオブジェクトを生成
7. **シリアライズ・出力**: export.serializeAndExport()でファイルに出力
8. **結果通知**: client.showMessage()で完了メッセージを表示

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

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

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

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

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|---------|--------------|
| CLI_DOC_DONE | Info | 出力完了時 | ドキュメント生成完了、出力ファイルパスを表示 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 出力パスへの書き込み失敗 | エラーをスロー |
| ワークスペース未準備 | ws.awaitReady()で待機 |
| ビルドスクリプト読み込み失敗 | エラーをスロー |

## 備考

- 出力されるJSONはdocUnion型のオブジェクト配列です
- Markdownはクラス単位でセクション分割されます
- Lua.hover.expandAliasを一時的にfalseに設定して処理します
- カスタムビルドスクリプト（Lua.docScriptPath）がある場合は適用されます

---

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

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

### 推奨読解順序

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

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

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

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

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

コマンドの起点となるファイルを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | exportDocument.lua | `script/core/command/exportDocument.lua` | メイン処理（8-15行目） |

**主要処理フロー**:
1. **9行目**: 出力パスを解決
2. **10行目**: doc.makeDoc()を呼び出し
3. **11-14行目**: 完了メッセージを表示

#### Step 3: ドキュメント生成処理を理解する

doc.makeDoc()の内部実装を追跡します。

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

**主要処理フロー**:
- **144行目**: ワークスペース準備待機
- **146-150行目**: hover.expandAliasを一時的にfalse設定
- **156行目**: プログレス表示開始
- **158行目**: ビルドスクリプトのインジェクション
- **160行目**: グローバル収集
- **162-165行目**: ドキュメント構築
- **167行目**: シリアライズ・出力

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

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

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

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

#### Step 5: シリアライズ・出力処理を理解する

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

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

**主要処理フロー**:
- **311-318行目**: JSON形式で出力
- **321-352行目**: Markdown形式で出力

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

```
workspace/executeCommand (lua.exportDocument)
    │
    └─ exportDocument.lua (エントリーポイント)
           │
           ├─ furi.decode() (出力パス解決)
           │
           └─ doc.makeDoc(outputPath)
                  │
                  ├─ ws.awaitReady()
                  │
                  ├─ config.set('hover.expandAlias', false)
                  │
                  ├─ progress.create()
                  │
                  ├─ injectBuildScript()
                  │
                  ├─ export.gatherGlobals()
                  │      └─ vm.getExportableGlobals()
                  │
                  ├─ export.makeDocs()
                  │      └─ export.documentObject()
                  │
                  └─ export.serializeAndExport()
                         ├─ jsonb.beautify() (JSON出力)
                         └─ markdown() (MD出力)
```

### データフロー図

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

{ args[1] } ───▶ exportDocument.lua ───▶ ファイル出力
                        │
                        ▼
                  doc.makeDoc()
                        │
                        ▼
                  gatherGlobals()
                        │
                        ▼
                  vm.global[] (グローバル一覧)
                        │
                        ▼
                  makeDocs()
                        │
                        ▼
                  docUnion[] (ドキュメントオブジェクト)
                        │
                        ▼
                  serializeAndExport()
                        │
                   ┌────┴────┐
                   ▼         ▼
              doc.json    doc.md
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| exportDocument.lua | `script/core/command/exportDocument.lua` | ソース | コマンドエントリーポイント |
| init.lua | `script/cli/doc/init.lua` | ソース | ドキュメント生成メインロジック |
| export.lua | `script/cli/doc/export.lua` | ソース | ドキュメントオブジェクト構築 |
| client.lua | `script/client.lua` | ソース | メッセージ表示 |
| file-uri.lua | `script/file-uri.lua` | ソース | URIエンコード/デコード |
| files.lua | `script/files.lua` | ソース | ファイルパス正規化 |
| language.lua | `script/language.lua` | ソース | 多言語メッセージ |
| vm.lua | `script/vm.lua` | ソース | グローバル収集 |
| json-beautify.lua | `script/json-beautify.lua` | ソース | JSON整形 |
| markdown.lua | `script/provider/markdown.lua` | ソース | Markdown生成 |
