# 機能設計書 76-ヘルプ表示

## 概要

本ドキュメントは、Lua Language ServerにおけるCLIヘルプ表示機能の設計を記述する。この機能は、コマンドラインオプションの一覧と各オプションの説明を表示し、ユーザーがCLI機能を正しく使用できるようにする。

### 本機能の処理概要

**業務上の目的・背景**：Lua Language Serverは複数のCLIオプション（--check, --doc, --logpath等）を提供している。ユーザーがこれらのオプションの使い方を把握するためには、分かりやすいヘルプメッセージが必要である。本機能はコマンドライン引数`--help`を指定した際に、利用可能なすべてのオプションとその説明を表示する。

**機能の利用シーン**：
- `lua-language-server --help` 実行時
- CLIオプションの確認時
- 使用例の参照時

**主要な処理内容**：
1. 定義された全オプションの走査
2. オプション名と型情報の表示
3. 説明文の整形表示
4. デフォルト値と使用例の表示
5. 選択可能な値の一覧表示

**関連システム・外部連携**：
- 標準出力への表示
- utilityモジュール（sortPairs）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ヘルプ表示 | 主画面 | コマンドライン引数の一覧を表示するCLI処理 |

## 機能種別

ヘルプ表示 / 情報出力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --help | flag | Yes | ヘルプ表示フラグ | - |

### 入力データソース

- help.lua内の`args`テーブル（オプション定義）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| helpText | string | 整形されたヘルプメッセージ |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

```
1. argsテーブルの走査
   └─ util.sortPairsでソート
2. 各オプションの処理
   └─ 名前、型、説明、デフォルト、例を取得
3. 整形出力
   └─ 各情報を適切にインデントして表示
```

### フローチャート

```mermaid
flowchart TD
    A[--help指定] --> B[argsテーブル走査]
    B --> C{boolean型?}
    C -->|Yes| D[オプション名のみ表示]
    C -->|No| E[オプション名=value形式で表示]
    D --> F{説明あり?}
    E --> F
    F -->|Yes| G[説明を整形して表示]
    F -->|No| H{次のオプション?}
    G --> I{型が配列?}
    I -->|Yes| J[選択可能値を表示]
    I -->|No| K{デフォルトあり?}
    J --> K
    K -->|Yes| L[デフォルト値を表示]
    K -->|No| M{例あり?}
    L --> M
    M -->|Yes| N[使用例を表示]
    M -->|No| H
    N --> H
    H -->|Yes| C
    H -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | ソート表示 | オプションはアルファベット順にソート | 常時 |
| BR-76-02 | 型表示 | boolean型は名前のみ、他は`=<value>`を付加 | 常時 |
| BR-76-03 | インデント | 説明文は4スペースでインデント | 常時 |
| BR-76-04 | 改行正規化 | 説明文の先頭・末尾の空白と改行を正規化 | 常時 |

### 計算ロジック

**説明文整形ロジック**:
```lua
-- 説明文の正規化
local normalized_description = attrs.description
    :gsub("^%s+", "")      -- 先頭空白削除
    :gsub("\n%s+", "\n")   -- 各行先頭空白削除
    :gsub("%s+$", "")      -- 末尾空白削除
-- 4スペースインデントで出力
print("\n    " .. normalized_description:gsub('\n', '\n    '))
```

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

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

本機能はデータベース操作を行わない。標準出力への表示のみ。

## エラー処理

### エラーケース一覧

本機能ではエラーは発生しない。すべてのオプション情報は静的に定義されている。

### リトライ仕様

リトライは不要。

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

トランザクション管理は不要。

## パフォーマンス要件

特になし。即時に表示される。

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

特になし。読み取り専用の情報表示機能。

## 備考

- オプション定義はhelp.lua内の`args`テーブルに集約
- 各オプションはtype, description, example, defaultを持つ

---

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

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

### 推奨読解順序

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

CLIオプション定義の構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | help.lua | `script/cli/help.lua` | 3-8行目: cli.argクラス定義 |

**読解のコツ**: `@class cli.arg`でオプションの型が定義されている。type, description, example, defaultの各フィールドを持つ。

#### Step 2: オプション定義を理解する

各CLIオプションの定義内容。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | help.lua | `script/cli/help.lua` | 10-147行目: argsテーブル - 全オプション定義 |

**主要オプション**:
- **11-15行目**: --help
- **16-22行目**: --check
- **54-62行目**: --doc
- **79-85行目**: --logpath
- **111-118行目**: --locale

#### Step 3: 表示処理を理解する

ヘルプメッセージの生成と表示。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | help.lua | `script/cli/help.lua` | 149-170行目: ヘルプ表示ループ |

**主要処理フロー**:
- **149行目**: util.sortPairsでソート走査
- **150-154行目**: オプション名と型の表示
- **155-158行目**: 説明文の整形と表示
- **159-162行目**: 型が配列の場合の値一覧表示
- **163-165行目**: デフォルト値の表示
- **166-168行目**: 使用例の表示

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

```
help.lua (スクリプト実行)
    │
    └─ util.sortPairs(args) でループ
           │
           ├─ オプション名表示
           │      └─ boolean型判定
           │
           ├─ 説明文表示
           │      └─ 正規化処理
           │
           ├─ 選択可能値表示
           │      └─ 型がtableの場合
           │
           ├─ デフォルト値表示
           │
           └─ 使用例表示
```

### データフロー図

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

args テーブル ─────────▶ util.sortPairs() ─────────▶ ソート済みリスト
                              │
                              ▼
                         各オプション処理
                              │
                              ├─▶ オプション名
                              │
                              ├─▶ 説明（整形済み）
                              │
                              ├─▶ 選択可能値
                              │
                              ├─▶ デフォルト値
                              │
                              └─▶ 使用例
                                      │
                                      ▼
                                  標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| help.lua | `script/cli/help.lua` | ソース | ヘルプ表示のメインモジュール |
| utility.lua | `script/utility.lua` | ソース | sortPairs関数 |
