# 機能設計書 48-ホバー情報

## 概要

本ドキュメントは、clojure-lspの「ホバー情報」機能（textDocument/hover）の設計を詳細に記載する。この機能は、シンボル上にマウスをホバーした際にドキュメントとシグネチャを表示するLSP機能である。

### 本機能の処理概要

**業務上の目的・背景**：コードリーディング中に関数や変数の詳細情報を素早く確認できることは、開発効率の向上に大きく寄与する。この機能により、エディタを離れることなくシンボルのドキュメント、シグネチャ、定義元ファイルを確認できる。

**機能の利用シーン**：開発者がコード内のシンボル（関数名、変数名、キーワード等）にマウスカーソルを合わせると、ポップアップでそのシンボルの情報が表示される。

**主要な処理内容**：
1. カーソル位置のシンボルを特定
2. シンボルの定義情報を取得
3. ドキュメント、シグネチャ、ファイル位置を整形
4. ClojureDocsからの追加情報を取得（オプション）
5. Markdown形式またはプレーンテキストで返却

**関連システム・外部連携**：LSP hover プロトコル、ClojureDocs連携。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | エディタ | 主画面 | マウスホバー時のポップアップ表示 |

## 機能種別

情報表示 / ドキュメント参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| text-document.uri | String | Yes | 対象ファイルURI | 有効なファイルURI |
| position.line | Number | Yes | 行位置（0始まり） | 非負整数 |
| position.character | Number | Yes | 列位置（0始まり） | 非負整数 |

### 入力データソース

- エディタからのホバーリクエスト
- clj-kondo解析結果（:analysis）
- ClojureDocsキャッシュ（オプション）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| range | Range | ホバー対象シンボルの範囲 |
| contents | MarkupContent or Array | ホバー内容 |
| contents.kind | String | "markdown" or "plaintext" |
| contents.value | String | 表示内容 |

### 出力先

- LSP textDocument/hover レスポンス

## 処理フロー

### 処理シーケンス

```
1. カーソル位置の要素を取得
   └─ q/find-element-under-cursor
2. 関数呼び出しコンテキストを確認
   └─ edit/find-function-usage-name-loc
3. 定義情報を取得
   └─ q/find-definition
4. ホバーコンテンツを構築
   └─ hover-documentation
   └─ シグネチャ、ドキュメント、ファイル位置を整形
5. ClojureDocs情報を追加（オプション）
   └─ f.clojuredocs/find-hover-docs-for
6. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[ホバーリクエスト] --> B[要素検出]
    B -->|検出失敗| Z[空contents返却]
    B -->|検出成功| C{定義存在?}
    C -->|はい| D[定義情報取得]
    C -->|いいえ| E[要素情報使用]
    D --> F[シグネチャ構築]
    E --> F
    F --> G[ドキュメント取得]
    G --> H{ClojureDocs有効?}
    H -->|はい| I[ClojureDocs取得]
    H -->|いいえ| J[コンテンツ整形]
    I --> J
    J --> K[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Markdown優先 | クライアントがMarkdownサポートする場合はMarkdown形式 | content-format確認 |
| BR-02 | シグネチャ表示 | arity-on-same-line?設定でシグネチャ表示形式を変更 | 設定時 |
| BR-03 | ファイル位置 | hide-file-location?設定でファイルパスを非表示 | 設定時 |
| BR-04 | 呼び出し情報 | hide-signature-call?設定で呼び出し情報を非表示 | 設定時 |
| BR-05 | ClojureDocs | :hover :clojuredocs 設定で有効/無効（デフォルト有効） | 設定時 |

### 計算ロジック

シグネチャ構築：
```clojure
(defn hover-signatures [{:keys [meta arglist-strs parameters]} join-char]
  (or (-> meta :arglists ...)       ; メタデータのarglists
      (some->> arglist-strs ...)    ; 解析から取得したarglist-strs
      (some->> parameters ...)))     ; Javaパラメータ
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | SELECT | 参照のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | N/A | シンボル検出失敗 | 空のcontents返却 |

### リトライ仕様

リトライなし

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

読み取り専用のため、トランザクション管理なし。

## パフォーマンス要件

- 応答時間: 100ms以内

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

特になし

## 備考

- CLJSファイルの場合、clojure名前空間をcljs名前空間に変換してClojureDocsを検索
- Java定義の場合、javaコードブロックを使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | hover.clj | `lib/src/clojure_lsp/feature/hover.clj` | hover関数の戻り値構造を理解 |

**読解のコツ**: MarkupContent と CodeBlock の使い分けを把握する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | handlers.clj | `lib/src/clojure_lsp/handlers.clj` | hover ハンドラ |

**主要処理フロー**:
- **388-393行目**: `hover` - LSPハンドラ

#### Step 3: ホバー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | hover.clj | `lib/src/clojure_lsp/feature/hover.clj` | hover, hover-documentation 関数 |

**主要処理フロー**:
- **214-260行目**: `hover` - メインロジック
- **144-212行目**: `hover-documentation` - コンテンツ構築
- **107-120行目**: `hover-signatures` - シグネチャ構築
- **69-105行目**: `find-docstring` - ドキュメント取得

#### Step 4: ClojureDocs連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | clojuredocs.clj | `lib/src/clojure_lsp/feature/clojuredocs.clj` | find-hover-docs-for |

**主要処理フロー**:
- **48-50行目**: `find-hover-docs-for` - ホバー用ClojureDocs取得

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

```
handlers/hover
    │
    └─ f.hover/hover
           │
           ├─ q/find-element-under-cursor
           ├─ edit/find-function-usage-name-loc
           ├─ q/find-definition
           │
           └─ hover-documentation
                  │
                  ├─ hover-signatures
                  │      └─ z/sexpr (arglists取得)
                  │
                  ├─ find-docstring
                  │      └─ q/find-definition-from-cursor (参照解決)
                  │
                  ├─ f.clojuredocs/find-hover-docs-for
                  │      └─ find-docs-for
                  │             └─ :clojuredocs :cache
                  │
                  └─ clojuredocs->hover-docs
                         └─ examples, see-alsos, notes 整形
```

### データフロー図

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

URI, Line, Col ───▶ find-element-under-cursor ───▶ cursor-element
                           │
                           ▼
                    find-definition ───▶ definition
                           │
                           ▼
               ┌───────────┴───────────┐
               │                       │
       hover-signatures       find-docstring
               │                       │
               ▼                       ▼
        シグネチャ文字列          ドキュメント文字列
               │                       │
               └───────────┬───────────┘
                           │
                           ▼
               find-hover-docs-for (optional)
                           │
                           ▼
                    MarkupContent
                           │
                           ▼
                  {:range :contents}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| hover.clj | `lib/src/clojure_lsp/feature/hover.clj` | ソース | ホバー情報のメインロジック |
| clojuredocs.clj | `lib/src/clojure_lsp/feature/clojuredocs.clj` | ソース | ClojureDocs連携 |
| handlers.clj | `lib/src/clojure_lsp/handlers.clj` | ソース | LSPハンドラ |
| queries.clj | `lib/src/clojure_lsp/queries.clj` | ソース | 解析データクエリ |
| edit.clj | `lib/src/clojure_lsp/refactor/edit.clj` | ソース | 編集ユーティリティ |
