# 機能設計書 64-@deprecated

## 概要

本ドキュメントは、Lua Language Serverにおける`@deprecated`アノテーション機能の設計を記述する。`@deprecated`は非推奨マーカーを付与するためのLuaDocアノテーションであり、関数や変数が将来的に削除予定であることを示し、使用時に警告を表示する機能を提供する。

### 本機能の処理概要

`@deprecated`アノテーションは、関数、変数、クラスなどに非推奨マーカーを付与する機能である。これにより、開発者は古いAPIの使用を避け、推奨される代替手段に移行することが促される。

**業務上の目的・背景**：ソフトウェア開発においてAPIの進化は避けられない。古いAPIを即座に削除すると後方互換性が損なわれるため、非推奨期間を設けて段階的に移行を促す必要がある。`@deprecated`アノテーションにより、コードベース内の非推奨APIの使用箇所を可視化し、計画的なリファクタリングを支援する。

**機能の利用シーン**：
- 古い関数を新しい関数に置き換える際のマーキング
- 将来のバージョンで削除予定のAPIの明示
- レガシーコードの使用を警告したい場合
- ライブラリ開発者がユーザーに移行を促す場合

**主要な処理内容**：
1. `---@deprecated`で始まるコメント行を検出
2. `doc.deprecated`ノードを生成
3. 直後の関数または変数定義にバインド
4. 診断機能と連携し、非推奨シンボルの使用箇所に警告を表示
5. エディタのUIで打ち消し線などの視覚的フィードバックを提供

**関連システム・外部連携**：
- パーサー（`script/parser/luadoc.lua`）：アノテーション構文の解析
- 診断機能（`script/core/diagnostics/deprecated.lua`）：非推奨警告の生成
- セマンティックトークン：打ち消し線の表示
- ホバー情報：非推奨メッセージの表示

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はエディタのコメント入力時に動作し、専用の画面は存在しない |

## 機能種別

コード解析 / メタデータ付与

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| コメントテキスト | string | Yes | `---@deprecated`で始まるコメント行 | `@deprecated`キーワードの存在確認 |

### 入力データソース

Luaソースファイル内の`---@deprecated`形式のコメント行

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc.deprecated | table | 非推奨マーカーのASTノード |
| start | integer | 開始位置 |
| finish | integer | 終了位置 |
| bindSource | table | バインドされたソースへの参照 |

### 出力先

パーサーの状態オブジェクト（`state.ast.docs`）に追加される

## 処理フロー

### 処理シーケンス

```
1. コメント解析開始
   └─ `---@deprecated`形式のコメントを検出
2. トークン解析
   └─ コメントテキストをトークンに分割
3. `deprecated`キーワード認識
   └─ docSwitch関数でdeprecatedケースにディスパッチ
4. ASTノード構築
   └─ `doc.deprecated`ノードを生成（シンプルなノード）
5. ソースバインディング
   └─ 直後の関数または変数定義にバインド
6. ドキュメントリストに追加
   └─ `state.ast.docs`にノードを追加
7. 診断連携
   └─ 非推奨シンボルの参照箇所を検出し警告生成
```

### フローチャート

```mermaid
flowchart TD
    A[コメント検出] --> B{@deprecatedキーワード?}
    B -->|No| Z[終了]
    B -->|Yes| C[doc.deprecatedノード生成]
    C --> D[位置情報設定]
    D --> E[ASTに追加]
    E --> F[bindDoc処理]
    F --> G{バインド対象あり?}
    G -->|Yes| H[関数/変数にバインド]
    G -->|No| I[バインドなし]
    H --> J[診断処理]
    I --> J
    J --> K[非推奨参照を検出]
    K --> L[警告生成]
    L --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | シンプルマーカー | @deprecatedは追加パラメータなしでも機能 | @deprecatedアノテーション使用時 |
| BR-02 | 関数バインド | 関数定義に対してバインド可能 | @deprecatedの後に関数定義がある場合 |
| BR-03 | 変数バインド | 変数定義に対してバインド可能 | @deprecatedの後に変数定義がある場合 |
| BR-04 | 参照警告 | 非推奨シンボルの参照時に警告を表示 | deprecated診断が有効な場合 |
| BR-05 | 視覚的表示 | エディタ上で打ち消し線表示 | セマンティックハイライト有効時 |

### 計算ロジック

特になし

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

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

本機能はデータベースを使用しない（メモリ上でAST操作を行う）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | @deprecatedの解析自体でエラーは発生しない | - |

### リトライ仕様

リトライは不要（構文解析時のエラーは即座に報告される）

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

トランザクション管理は不要（メモリ上の解析処理）

## パフォーマンス要件

- @deprecatedの解析は0.1ms以内に完了すること
- 診断による非推奨警告の検出はファイルあたり10ms以内

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

特になし

## 備考

- `@deprecated`は単独で使用可能（追加パラメータ不要）
- 他のアノテーション（`@param`、`@return`等）と組み合わせて使用可能
- 診断機能の設定で警告レベルを調整可能

---

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

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

### 推奨読解順序

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

まず、`@deprecated`アノテーションがどのようなASTノードとして表現されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | luadoc.lua | `script/parser/luadoc.lua` | `doc.deprecated`ノードの構造（非常にシンプル） |

**読解のコツ**: `doc.deprecated`ノードは以下のフィールドを持つ：
- `type`: `'doc.deprecated'`
- `start`: 開始位置
- `finish`: 終了位置
追加のフィールドはなく、最もシンプルなアノテーションの一つ。

#### Step 2: エントリーポイントを理解する

`@deprecated`アノテーションの解析処理の起点を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | luadoc.lua | `script/parser/luadoc.lua` | `docSwitch`の`'deprecated'`ケース（1349-1356行目） |

**主要処理フロー**:
1. **1350-1355行目**: シンプルなテーブルを返却
   - `type = 'doc.deprecated'`
   - `start = getFinish()`
   - `finish = getFinish()`

このケースは非常にシンプルで、追加の解析処理は行わない。

#### Step 3: バインディング処理を理解する

非推奨マーカーがソースコードにバインドされる仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | luadoc.lua | `script/parser/luadoc.lua` | `bindDoc`関数内のdeprecated処理（1950-1965行目） |

**主要処理フロー**:
- **1951行目**: `doc.type == 'doc.deprecated'`の条件分岐
- **1960-1962行目**: 関数またはパラメータでなければバインド
- **1963-1965行目**: `bindDocWithSource`でソースに関連付け

#### Step 4: 診断機能を理解する

非推奨シンボルの使用を検出する診断機能を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | deprecated.lua | `script/core/diagnostics/deprecated.lua` | 非推奨診断の実装 |

**主要処理フロー**:
- 非推奨マーカーが付いたシンボルへの参照を検出
- 警告レベルの診断メッセージを生成
- エディタに診断結果を返却

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

```
luadoc (メイン関数)
    │
    ├─ buildLuaDoc
    │      └─ convertTokens
    │             └─ docSwitch('deprecated')
    │                    └─ シンプルなノード返却
    │
    └─ bindDocs
           └─ bindDocsBetween
                  └─ bindDoc
                         └─ doc.deprecated処理
                                └─ ソースへのバインド

診断処理 (別プロセス)
    │
    └─ deprecated診断
           ├─ 非推奨マーカーの収集
           ├─ 参照箇所の検出
           └─ 警告生成
```

### データフロー図

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

---@deprecated
function oldFunc() end
        │
        ▼
  parseTokens              ───▶  トークン配列
        │
        ▼
  docSwitch('deprecated')  ───▶  deprecatedケース処理
        │
        ▼
  シンプルノード生成       ───▶  {type: 'doc.deprecated', ...}
        │
        ▼
  bindDoc                  ───▶  関数定義にバインド
        │
        ▼
  state.ast.docs に追加    ───▶  完成したASTノード
        │
        ▼
  診断処理                 ───▶  oldFunc()の参照に警告
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| luadoc.lua | `script/parser/luadoc.lua` | ソース | LuaDocアノテーションの解析メイン処理 |
| deprecated.lua | `script/core/diagnostics/deprecated.lua` | ソース | 非推奨診断の実装 |
| semantic-tokens.lua | `script/core/semantic-tokens.lua` | ソース | 打ち消し線などの視覚的フィードバック |
| hover/init.lua | `script/core/hover/init.lua` | ソース | ホバー情報に非推奨マーカーを表示 |
| compile.lua | `script/parser/compile.lua` | ソース | Luaソースコードのコンパイル |
