# 機能設計書 57-@type アノテーション

## 概要

本ドキュメントは、Lua Language Serverにおける`@type`アノテーション機能の設計を記載する。この機能は、変数やフィールドの型を明示的に指定するためのアノテーションを提供する。

### 本機能の処理概要

`@type`アノテーションは、直後の変数宣言や代入文に対して型情報を付与する機能である。型推論だけでは判断できない場合や、明示的に型を指定したい場合に使用される。

**業務上の目的・背景**：Luaの動的型付けでは、コード上から型を判断できない場合がある。`@type`アノテーションにより、開発者が意図する型を明示でき、型推論の精度向上とコード補完の改善が図れる。

**機能の利用シーン**：
- 変数宣言時の型指定
- 関数戻り値の受け取り時
- グローバル変数の型定義
- any型からの型絞り込み

**主要な処理内容**：
1. `---@type`コメントの解析
2. 型式の解析（parseType）
3. Union型の対応
4. 直後のソース要素へのバインド

**関連システム・外部連携**：LuaDoc解析、型推論と連携。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ホバー情報表示 | 主機能 | 型情報の表示 |

## 機能種別

データ定義 / 型指定

## 入力仕様

### 入力パラメータ

アノテーション構文：
```lua
---@type Type1|Type2|...
local x = value

---@type Type1, Type2, Type3
local a, b, c = func()
```

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Type | string | Yes | 型名（Union型、配列型、関数型等可） | 有効な型式 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.type | parser.object | 型定義ASTノード |
| doc.type.types | array | 型ユニットのリスト（Union型の場合は複数） |
| optional | boolean | nil許容フラグ（?付き） |

### 出力先

- ast.docs（ドキュメント配列）
- source.bindDocs（ソースへのバインド）

## 処理フロー

### 処理シーケンス

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

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

3. 複数型対応
   └─ カンマ区切りの複数型を解析

4. ソースバインド
   └─ 直後の変数宣言にバインド
```

### フローチャート

```mermaid
flowchart TD
    A[---@type検出] --> B[parseType実行]
    B --> C{型解析成功?}
    C -->|No| D[nilを返却]
    C -->|Yes| E{カンマ存在?}
    E -->|Yes| F[追加の型を解析]
    F --> E
    E -->|No| G[doc.typeノード返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-01 | 型必須 | 少なくとも1つの型が必要 | 常時 |
| BR-57-02 | Union型 | `\|`区切りで複数型を指定可能 | Union型 |
| BR-57-03 | Optional | `?`で省略可能（nil許容）を表現 | Optional型 |
| BR-57-04 | 複数変数 | カンマ区切りで複数変数の型を一度に指定 | 多値代入 |

### 計算ロジック

**型指定例**：
```lua
---@type string
local name = getName()

---@type number|nil
local value = getValue()

---@type string, number, boolean
local a, b, c = func()

---@type string[]
local list = {}

---@type fun(x: number): string
local converter = function(x) return tostring(x) end
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- `@type`は変数宣言の直前に配置する必要がある
- 推論より`@type`指定が優先される

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **1097行目**: parseType()で最初の型を解析
2. **1102-1108行目**: カンマ区切りの追加型を解析
3. **1110行目**: first（doc.type）と rests を返却

#### Step 2: 型解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | luadoc.lua | `script/parser/luadoc.lua` | parseType関数（944-1037行目） |
| 2-2 | luadoc.lua | `script/parser/luadoc.lua` | parseTypeUnit関数（885-919行目） |

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

```
docSwitch 'type'
    │
    ├─ parseType()
    │      │
    │      └─ parseTypeUnit(result)
    │             ├─ parseFunction(parent)
    │             ├─ parseTable(parent)
    │             ├─ parseString(parent)
    │             ├─ parseName('doc.type.name', parent)
    │             └─ ...
    │
    └─ [カンマ区切りループ]
           └─ parseType()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| luadoc.lua | `script/parser/luadoc.lua` | ソース | @type解析 |
| compiler.lua | `script/vm/compiler.lua` | ソース | doc.typeの処理（bindDocs） |
