# 画面設計書 26-インレイヒント（textDocument/inlayHint）

## 概要

本ドキュメントは、serve-d LSPサーバーにおける `textDocument/inlayHint` リクエストの処理仕様を定義する画面設計書である。D言語ソースコード上にインラインで型推論結果等のヒント情報を表示する機能を記述する。

### 本画面の処理概要

**業務上の目的・背景**：D言語では `auto` キーワードや型推論により、変数の型がソースコード上に明示されないことがある。インレイヒント機能は、そのような暗黙の型情報をエディタ上にインラインで表示することで、コードの可読性を向上させる。LSPプロトコルの `textDocument/inlayHint` を通じて実現される。DCDコンポーネントの `getInlayHints` を使用して型情報を取得する。

**画面へのアクセス方法**：エディタがD言語ソースファイルを表示している際に、自動的に `textDocument/inlayHint` リクエストをLSPサーバーに送信する。ユーザーが明示的に操作する必要はなく、エディタの設定でインレイヒントが有効化されていれば自動的に表示される。

**主要な操作・処理内容**：
1. DCDコンポーネントの `getInlayHints` を使用してドキュメント全体のインレイヒント情報を取得する
2. 各ヒントについて、種別（型ヒント等）と表示位置を設定する
3. `InlayHint[]` 配列としてエディタに返却する

**画面遷移**：本機能は独立した情報提供機能であり、他の画面への遷移は発生しない。

**権限による表示制御**：権限による表示制御は存在しない。D言語ファイルであれば一律にインレイヒントが提供される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 32 | インレイヒント (textDocument/inlayHint) | 主機能 | 型推論結果等のインレイヒントをエディタに提供する |

## 画面種別

情報提供（LSPプロトコルレスポンス）

## URL/ルーティング

- LSPメソッド: `textDocument/inlayHint`

## 入出力項目

| 項目名 | 型 | 入力/出力 | 必須 | 説明 |
|--------|-----|----------|------|------|
| params.textDocument.uri | DocumentUri | 入力 | Yes | 対象ドキュメントのURI |
| params.range | TextRange | 入力 | Yes | 対象範囲（LSPプロトコル仕様、ただし現在の実装ではドキュメント全体を処理） |
| InlayHint[] | InlayHint[] | 出力 | - | インレイヒント情報の配列 |
| InlayHint.position | Position | 出力 | - | ヒントの表示位置 |
| InlayHint.label | string | 出力 | - | ヒントのラベル文字列（識別子名等） |
| InlayHint.kind | InlayHintKind | 出力 | - | ヒントの種別（typeの場合あり） |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|---------|------|
| 型ヒント | インラインテキスト | 変数宣言等の横にグレー等の薄い文字で型情報が表示される |

## イベント仕様

### 1-インレイヒント取得

エディタがビューポートの変更やドキュメントの更新時にトリガーする処理フロー。

1. `backend.getBestInstance!DCDComponent` でカレントファイルに最適なDCDインスタンスを取得する（行12-13）
2. インスタンスが存在しない場合は `null` を返却する（行14-15）
3. ドキュメントを取得し、言語IDが `"d"` でなければ `null` を返却する（行17-19）
4. `instance.get!DCDComponent.getInlayHints` でドキュメント全体のインレイヒントを取得する（行21）
5. 結果が空の場合は `null` を返却する（行22-23）
6. 各ヒントについて:
   a. `kind` が `'l'` の場合、`InlayHintKind.type` を設定する（行34-35）
   b. `movePositionBytes` でバイトオフセットをPositionに変換する（行40）
   c. ラベルにidentifier文字列を設定する（行41）
7. `InlayHint[]` 配列を返却する（行44）

## データベース更新仕様

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

本機能はデータベースに対する操作を行わない。DCDの解析結果を参照する読み取り専用の処理である。

## メッセージ仕様

本機能は明示的なメッセージ表示を行わない。

## 例外処理

| 条件 | 挙動 |
|------|------|
| DCDコンポーネントが利用不可 | `null` を返却 |
| D言語ファイル以外 | `null` を返却 |
| DCDがインレイヒントを返さない | `null` を返却 |

## 備考

- 現在の実装では、DCDから返されるヒントの `kind` が `'l'` の場合のみ `InlayHintKind.type` が設定される。それ以外のkind値はdefaultケースでスキップされる（kindフィールドは未設定のまま）
- `params.range` パラメータは現在の実装では使用されておらず、ドキュメント全体のインレイヒントが取得される
- `Appender` を使用して効率的に結果配列を構築している

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protocol.d | `source/served/lsp/protocol.d` | `InlayHint`, `InlayHintKind`, `InlayHintParams` の定義を確認 |

**読解のコツ**: `InlayHintKind` は `type`(1) と `parameter`(2) の2種類が定義されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inlay_hints.d | `source/served/commands/inlay_hints.d` | `provideInlayHints` 関数（行9-45）がLSPリクエストハンドラ |

**主要処理フロー**:
1. **行9**: `@protocolMethod("textDocument/inlayHint")` でバインド
2. **行12-15**: DCDインスタンス取得、なければnull
3. **行17-19**: 言語ID確認
4. **行21**: `getInlayHints` でDCDにヒント情報を問い合わせ
5. **行29-43**: 各ヒントの種別・位置・ラベルを設定
6. **行44**: 結果配列を返却

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

```
textDocument/inlayHint リクエスト
    |
    +-- provideInlayHints (inlay_hints.d:9)
           |
           +-- backend.getBestInstance!DCDComponent (インスタンス取得)
           +-- documents[uri] (ドキュメント取得)
           +-- DCDComponent.getInlayHints (DCD呼び出し)
           +-- movePositionBytes (位置変換)
           +-- Appender!(InlayHint[]) (結果配列構築)
```

### データフロー図

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

InlayHintParams ----------> provideInlayHints ------------> InlayHint[]
  textDocument.uri            |
  range                       +-- DCDComponent.getInlayHints
                              |      --> (kind, symbolLocation, identifier)[]
                              +-- kind変換 ('l' -> type)
                              +-- 位置変換 (bytes -> Position)
                              +-- ラベル設定 (identifier)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inlay_hints.d | `source/served/commands/inlay_hints.d` | ソース | インレイヒントの主処理 |
| types.d | `source/served/types.d` | ソース | 共通型定義 |
| protocol.d | `source/served/lsp/protocol.d` | ソース | LSPプロトコル型定義 |
| events.d | `source/served/utils/events.d` | ソース | activeInstance等のイベント関連ユーティリティ |
