# 機能設計書 59-@return アノテーション

## 概要

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

### 本機能の処理概要

`@return`アノテーションは、関数定義の直前に配置し、関数が返す値の型と説明を指定する機能である。Luaは多値戻りをサポートするため、複数の戻り値型を定義できる。

**業務上の目的・背景**：関数の戻り値型を明示することで、呼び出し側で正しい型を期待してコードを書けるようになり、型推論の精度も向上する。

**機能の利用シーン**：
- 関数定義時の戻り値型指定
- APIドキュメントの生成
- 戻り値の型チェック
- 関数呼び出し結果の型推論

**主要な処理内容**：
1. `---@return`コメントの解析
2. 型式の解析（複数可）
3. 戻り値名の解析（オプション）
4. 説明コメントの抽出
5. 関数へのバインド

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

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

## 関連画面

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

## 機能種別

データ定義 / 戻り値型指定

## 入力仕様

### 入力パラメータ

アノテーション構文：
```lua
---@return Type1[?] [name1] [, Type2[?] [name2], ...]
```

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Type | string | Yes | 型名 | 有効な型式 |
| ? | symbol | No | 省略可能フラグ（戻り値がないこともある） | - |
| name | string | No | 戻り値の名前 | 有効な識別子 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.return | parser.object | 戻り値定義ASTノード |
| doc.return.returns | array | 戻り値型のリスト |
| returnIndex | integer | 戻り値の順序インデックス |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

2. 戻り値ループ
   └─ カンマ区切りで複数の戻り値を解析

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

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

5. 名前解析
   └─ 戻り値名をオプションで解析

6. 関数へのバインド
   └─ 関数定義にバインド
```

### フローチャート

```mermaid
flowchart TD
    A[---@return検出] --> B[戻り値ループ開始]
    B --> C[parseType実行]
    C --> D{型解析成功?}
    D -->|No| E[ループ終了]
    D -->|Yes| F{?存在?}
    F -->|Yes| G[optional=true]
    F -->|No| H[名前解析]
    G --> H
    H --> I[returns配列に追加]
    I --> J{カンマ存在?}
    J -->|Yes| B
    J -->|No| K{returns空?}
    K -->|Yes| L[nil返却]
    K -->|No| M[doc.returnノード返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | 型必須 | 少なくとも1つの型が必要 | 常時 |
| BR-59-02 | 多値戻り | カンマ区切りで複数の戻り値を定義可能 | 多値戻り関数 |
| BR-59-03 | Optional | `?`で省略可能な戻り値を表現 | 条件付き戻り値 |
| BR-59-04 | 名前付き | 戻り値に名前を付けてドキュメント化可能 | ドキュメント用 |
| BR-59-05 | 可変長 | `...`で可変長戻り値を表現 | イテレータ等 |

### 計算ロジック

**戻り値定義例**：
```lua
---@return string name ユーザー名を返す
function getName()
end

---@return number, string id, name
function getInfo()
end

---@return boolean? success 成功時true、失敗時nil
function tryAction()
end

---@return ...string 文字列のリストを返す
function getStrings()
end
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 戻り値なし | 型が1つも指定されていない | nil返却 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- 複数の`@return`行で複数の戻り値を定義することも可能
- 戻り値インデックスは自動的に割り当てられる

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **1181-1185行目**: `...`戻り値名の事前チェック
2. **1186行目**: parseTypeで型解析
3. **1193-1196行目**: `?`でoptionalをチェック
4. **1197-1203行目**: 戻り値名の解析
5. **1204-1208行目**: カンマで次の戻り値へ

#### Step 2: インデックス割り当てを理解する

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

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

```
docSwitch 'return'
    │
    ├─ parseDots('doc.return.name') [事前チェック]
    │
    ├─ [戻り値ループ]
    │      │
    │      ├─ parseType(result)
    │      │
    │      ├─ parseName('doc.return.name', docType)
    │      │  └─ parseDots('doc.return.name', docType)
    │      │
    │      └─ returns配列に追加
    │
    └─ doc.return返却

bindReturnIndex(binded)
    │
    └─ [doc.returnごと]
           └─ rtn.returnIndex = index
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| luadoc.lua | `script/parser/luadoc.lua` | ソース | @return解析 |
| compiler.lua | `script/vm/compiler.lua` | ソース | 戻り値型の推論 |
| return.lua | `script/core/hover/return.lua` | ソース | ホバーでの戻り値表示 |
