# 通知設計書 86-CLI_DOC_INITING

## 概要

本ドキュメントは、Lua Language Serverのコマンドラインドキュメント生成機能における「ドキュメント読み込み中」通知（CLI_DOC_INITING）の設計を記載する。

### 本通知の処理概要

CLI_DOC_INITINGは、コマンドラインでドキュメント生成（--DOCオプション）を実行する際に、初期化処理が開始されたことを示す通知メッセージである。

**業務上の目的・背景**：ドキュメント生成機能は、Luaソースコードからアノテーション情報を抽出し、APIドキュメントを自動生成する。この処理はワークスペースの読み込みと解析を必要とするため、初期化に時間がかかる場合がある。本通知は、ユーザーに処理が開始されたことを伝え、待機が必要であることを示す。

**通知の送信タイミング**：ドキュメント生成のCLI実行が開始された直後、ワークスペースの準備が完了する前に表示される。

**通知の受信者**：コマンドラインで`--DOC`オプションを実行しているユーザー。標準出力（コンソール）に直接表示される。

**通知内容の概要**：「ドキュメントを読み込んでいます...」という形式で、初期化処理が進行中であることを示す。

**期待されるアクション**：ユーザーは初期化が完了するまで待機する。プログレス表示が続くため、処理が進行中であることを確認できる。

## 通知種別

コンソール出力（CLI標準出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | なし |

### 送信先決定ロジック

コマンドラインでドキュメント生成を実行しているプロセスの標準出力に直接出力される。常に表示される（抑止条件なし）。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| 形式 | プレーンテキスト |

### 本文テンプレート

```
日本語:
ドキュメントを読み込んでいます...

英語:
Loading documents ...
```

### 添付ファイル

なし

## テンプレート変数

なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | ドキュメント生成開始 | 常に表示 | --DOCオプション実行時 |

### 送信抑止条件

なし（常に表示）

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[CLI DOC実行開始] --> B[rootUri検証]
    B --> C[CLI_DOC_INITING表示]
    C --> D[lclient初期化]
    D --> E[ワークスペース準備待ち]
    E --> F[ドキュメント生成処理]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本機能はデータベースを使用しない。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | - |

### 更新テーブル一覧

なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 出力失敗 | コンソール出力が不可能な場合 | 処理は継続 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1回のドキュメント生成あたり | 最大1回 |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（CLI実行時のみ）

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

- 機密情報は含まれない（固定メッセージのみ）

## 備考

- 本通知はio.write()で出力されるため、改行なしで表示される
- 後続のプログレスバーが同じ行に追記される
- ワークスペースの読み込みが完了すると、プログレスバーの更新が始まる

---

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

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

### 推奨読解順序

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

処理の起点となる関数を特定する。

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

**主要処理フロー**:
1. **177行目**: `lang(LOCALE)` でローカライゼーション初期化
2. **183-185行目**: DOC引数の検証
3. **217行目**: `io.write(lang.script('CLI_DOC_INITING'))` で通知表示
4. **222行目**: `ws.awaitReady(rootUri)` でワークスペース準備待ち

#### Step 2: 通知出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | init.lua | `script/cli/doc/init.lua` | 217行目の`io.write()`呼び出し |

**読解のコツ**: `io.write()`は改行なしで出力するため、後続のプログレスバーが同じ行に続く。

#### Step 3: ローカライゼーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | script.lua | `locale/en-us/script.lua` | 684-685行目でメッセージ定義 |
| 3-2 | script.lua | `locale/ja-jp/script.lua` | 685-686行目で日本語メッセージ定義 |

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

```
doc.runCLI() [init.lua:176]
    │
    ├─ lang(LOCALE) [init.lua:177]
    │      └─ ローカライゼーション初期化
    │
    ├─ DOC引数検証 [init.lua:183-185]
    │
    ├─ rootUri生成 [init.lua:188-192]
    │
    ├─ lclient():start() [init.lua:210]
    │      │
    │      ├─ client:initialize() [init.lua:213-216]
    │      │
    │      ├─ io.write(CLI_DOC_INITING) [init.lua:217]
    │      │
    │      ├─ ws.awaitReady() [init.lua:222]
    │      │
    │      └─ ドキュメント生成処理 [init.lua:227-254]
    │
    └─ 終了
```

### データフロー図

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

--DOC引数 ─────────▶ rootUri検証 ───────▶ lclient初期化
                          │
                          ▼
               io.write(CLI_DOC_INITING) ───────▶ コンソール出力
                          │
                          ▼
                ws.awaitReady() ───────▶ ワークスペース準備完了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| init.lua | `script/cli/doc/init.lua` | ソース | ドキュメント生成CLI処理 |
| export.lua | `script/cli/doc/export.lua` | ソース | ドキュメントエクスポート処理 |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ定義 |
