# 機能設計書 58-@param アノテーション

## 概要

本ドキュメントは、Lua Language Serverにおける`@param`アノテーション機能の設計を記載する。この機能は、関数のパラメータ（引数）に対して型情報と説明を付与するためのアノテーションを提供する。

### 本機能の処理概要

`@param`アノテーションは、関数定義の直前に配置し、各引数の型と説明を指定する機能である。シグネチャヘルプやホバー表示で引数情報として表示される。

**業務上の目的・背景**：関数の引数型を明示することで、呼び出し側で正しい型の値を渡しているかを検証でき、また開発者が関数の使い方を理解しやすくなる。

**機能の利用シーン**：
- 関数定義時の引数型指定
- APIドキュメントの生成
- 引数の型チェック
- シグネチャヘルプでの引数情報表示

**主要な処理内容**：
1. `---@param`コメントの解析
2. パラメータ名の解析
3. 型式の解析
4. 説明コメントの抽出
5. 関数引数へのバインド

**関連システム・外部連携**：LuaDoc解析、型推論、シグネチャヘルプと連携。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | シグネチャヘルプ | 主機能 | 引数情報の表示 |
| 1 | ホバー情報表示 | 補助機能 | 関数の引数型を表示 |

## 機能種別

データ定義 / パラメータ型指定

## 入力仕様

### 入力パラメータ

アノテーション構文：
```lua
---@param paramName[?] Type [description]
```

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| paramName | string | Yes | パラメータ名（`...`も可） | 有効な識別子または`...` |
| ? | symbol | No | 省略可能フラグ | - |
| Type | string | Yes | 型名 | 有効な型式 |
| description | string | No | 説明文 | - |

### 入力データソース

- Luaソースコード内の`---@param`コメント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.param | parser.object | パラメータ定義ASTノード |
| doc.param.param | parser.object | パラメータ名ノード |
| doc.param.extends | parser.object | 型ノード |
| optional | boolean | 省略可能フラグ |

### 出力先

- ast.docs（ドキュメント配列）
- 対応する引数へのバインド

## 処理フロー

### 処理シーケンス

```
1. トークン解析
   └─ `param`キーワードを検出

2. パラメータ名解析
   └─ parseName または parseDots

3. Optionalチェック
   └─ `?`の有無を確認

4. 型解析
   └─ parseType()で型式を解析

5. 関数へのバインド
   └─ 関数の対応する引数にバインド
```

### フローチャート

```mermaid
flowchart TD
    A[---@param検出] --> B[パラメータ名解析]
    B --> C{名前存在?}
    C -->|No| D[LUADOC_MISS_PARAM_NAME警告]
    C -->|Yes| E{?存在?}
    E -->|Yes| F[optional=true]
    E -->|No| G[型解析]
    F --> G
    G --> H{型解析成功?}
    H -->|No| I[LUADOC_MISS_PARAM_EXTENDS警告]
    H -->|Yes| J[doc.paramノード返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-58-01 | 名前必須 | パラメータ名は必須 | 常時 |
| BR-58-02 | 型必須 | 型は必須 | 常時 |
| BR-58-03 | Optional | `?`で省略可能を表現 | 省略可能引数 |
| BR-58-04 | 可変長 | `...`で可変長引数を表現 | 可変長引数 |
| BR-58-05 | 自己参照 | `self`でメソッドの自己参照を定義 | メソッド |

### 計算ロジック

**パラメータ定義例**：
```lua
---@param name string ユーザー名
---@param age? number 年齢（省略可能）
---@param ... any 追加の引数
function createUser(name, age, ...)
end

---@param self MyClass
---@param value number
function MyClass:setValue(value)
end
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| LUADOC_MISS_PARAM_NAME | パラメータ名不足 | パラメータ名が指定されていない | 警告を出力 |
| LUADOC_MISS_PARAM_EXTENDS | 型不足 | 型が指定されていない | 警告を出力 |

### リトライ仕様

リトライは行わない。

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

トランザクションは使用しない。

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- パラメータ名は実際の関数引数名と一致させる必要がある
- 順序は関係なく、名前でマッチングされる

---

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

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

### 推奨読解順序

#### Step 1: 解析処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | luadoc.lua | `script/parser/luadoc.lua` | docSwitch 'param'（1141-1174行目） |

**主要処理フロー**:
1. **1146-1147行目**: parseNameまたはparseDots
2. **1156-1159行目**: `?`でoptionalをチェック
3. **1162行目**: parseTypeで型を解析
4. **1163-1169行目**: 型がない場合は警告

#### Step 2: バインド処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | luadoc.lua | `script/parser/luadoc.lua` | bindDoc関数内のdoc.param処理（1984-2010行目） |

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

```
docSwitch 'param'
    │
    ├─ parseName('doc.param.name', result)
    │  └─ parseDots('doc.param.name', result)
    │
    └─ parseType(result)

bindDoc(source, binded)
    │
    └─ [doc.param]
           └─ source.args内で名前マッチング
                  └─ bindDocWithSource(doc, arg)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| luadoc.lua | `script/parser/luadoc.lua` | ソース | @param解析 |
| compiler.lua | `script/vm/compiler.lua` | ソース | doc.paramの処理 |
| signature.lua | `script/core/signature.lua` | ソース | シグネチャヘルプでの利用 |
