# 機能設計書 56-@class アノテーション

## 概要

本ドキュメントは、Lua Language Serverにおける`@class`アノテーション機能の設計を記載する。この機能は、Luaコード内でクラス（オブジェクト指向プログラミングにおけるクラス概念）を定義し、型システムに登録する機能を提供する。

### 本機能の処理概要

`@class`アノテーションは、テーブルをクラスとして定義し、継承関係やフィールド定義を記述するための機能である。定義されたクラスは型として使用でき、型推論やコード補完で活用される。

**業務上の目的・背景**：Luaはプロトタイプベースのオブジェクト指向をサポートするが、言語仕様として明示的なクラス定義を持たない。`@class`アノテーションにより、開発者はクラス構造を明示的に定義でき、IDEによる型チェック、コード補完、ドキュメント生成の恩恵を受けられる。

**機能の利用シーン**：
- オブジェクト指向パターンの実装時
- メタテーブルを使用したクラス定義時
- ライブラリAPIの型定義時
- 複雑なデータ構造の定義時

**主要な処理内容**：
1. `---@class`コメントの解析
2. クラス名の抽出
3. 継承関係（extends）の解析
4. ジェネリック型パラメータの解析
5. グローバル型としての登録
6. 後続の`@field`との紐付け

**関連システム・外部連携**：LuaDoc解析、型推論、コード補完、ホバー表示と連携。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ホバー情報表示 | 主機能 | クラス情報の表示 |
| 2 | コード補完 | 補助機能 | クラスのフィールド補完 |

## 機能種別

データ定義 / 型定義

## 入力仕様

### 入力パラメータ

アノテーション構文：
```lua
---@class [(exact)] ClassName[<T, K, ...>] [: ParentClass[, ParentClass2, ...]]
```

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (exact) | attribute | No | 厳密なクラス（追加フィールド禁止） | - |
| ClassName | string | Yes | クラス名 | 有効な識別子 |
| <T, K, ...> | generic | No | ジェネリック型パラメータ | - |
| ParentClass | string | No | 継承元クラス | 有効な型名 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.class | parser.object | クラス定義ASTノード |
| doc.class.class | parser.object | クラス名ノード |
| doc.class.extends | array | 継承元リスト |
| doc.class.signs | array | ジェネリック型パラメータ |
| doc.class.fields | array | フィールド定義リスト |

### 出力先

- ast.docs（ドキュメント配列）
- グローバル型テーブル

## 処理フロー

### 処理シーケンス

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

2. 属性解析
   └─ (exact)等のdocAttrを解析

3. クラス名解析
   └─ parseName('doc.class.name', result)

4. ジェネリック解析
   └─ parseSigns(result)

5. 継承解析
   └─ `:`後のparseNameまたはparseTable

6. フィールド紐付け
   └─ 後続の@fieldを収集

7. グローバル登録
   └─ vm.declareGlobalで型として登録
```

### フローチャート

```mermaid
flowchart TD
    A[---@class検出] --> B[docAttr解析]
    B --> C{クラス名存在?}
    C -->|No| D[LUADOC_MISS_CLASS_NAME警告]
    C -->|Yes| E[クラス名保存]
    E --> F{<存在?}
    F -->|Yes| G[ジェネリック解析]
    F -->|No| H{:存在?}
    G --> H
    H -->|Yes| I[継承元解析]
    H -->|No| J[doc.classノード生成]
    I --> J
    J --> K[グローバル型登録]
    K --> L[@field収集]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-01 | クラス名必須 | クラス名は必須 | 常時 |
| BR-56-02 | 多重継承 | 複数の親クラスを指定可能 | カンマ区切り |
| BR-56-03 | exact属性 | (exact)指定時は追加フィールド禁止 | 属性指定時 |
| BR-56-04 | field紐付け | 直後の@fieldはこのクラスに属する | @class直後の@field |
| BR-56-05 | ジェネリック | <T>形式でジェネリック型パラメータを定義可能 | ジェネリッククラス |

### 計算ロジック

**クラス定義例**：
```lua
---@class MyClass : ParentClass
---@field name string
---@field age number

---@class (exact) StrictClass
---@field id number

---@class Container<T>
---@field items T[]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| LUADOC_MISS_CLASS_NAME | クラス名不足 | クラス名が指定されていない | 警告を出力 |
| LUADOC_MISS_CLASS_EXTENDS_NAME | 継承元不足 | `:`の後に継承元がない | 警告を出力 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- クラスはグローバル型として登録され、ファイル間で共有される
- 同名クラスの再定義は追加フィールドとしてマージされる

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **1048行目**: parseDocAttrで属性解析
2. **1049行目**: parseNameでクラス名解析
3. **1060行目**: parseSignsでジェネリック解析
4. **1068-1092行目**: 継承元の解析（parseName, parseTable, parseTuple）

#### Step 2: フィールド紐付けを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | luadoc.lua | `script/parser/luadoc.lua` | bindCommentsAndFields（2118-2171行目） |

**主要処理フロー**:
- **2123-2139行目**: doc.classの場合のフィールド収集
- **2135-2139行目**: doc.fieldをclass.fieldsに追加

#### Step 3: グローバル型登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compiler.lua | `script/vm/compiler.lua` | doc.classの処理 |
| 3-2 | global.lua | `script/vm/global.lua` | vm.declareGlobal |

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

```
docSwitch 'class'
    │
    ├─ parseDocAttr(result)
    │
    ├─ parseName('doc.class.name', result)
    │
    ├─ parseSigns(result)
    │
    └─ [継承解析]
           ├─ parseName('doc.extends.name', result)
           ├─ parseTable(result)
           └─ parseTuple(result)

bindCommentsAndFields(binded)
    │
    └─ [doc.classの場合]
           └─ class.fields[#class.fields+1] = doc
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| luadoc.lua | `script/parser/luadoc.lua` | ソース | @class解析 |
| compiler.lua | `script/vm/compiler.lua` | ソース | 型推論での@class処理 |
| global.lua | `script/vm/global.lua` | ソース | グローバル型登録 |
