# 機能設計書 63-ドキュメント・定義ジャンプ

## 概要

本ドキュメントは、Doom Emacsにおけるドキュメント・定義ジャンプモジュール（lookup）の機能設計を記述する。本モジュールは「What am I looking at?」という問いに答えるための統合的なルックアップ機能を提供する。

### 本機能の処理概要

lookupモジュールは、シンボルの定義へのジャンプ、リファレンス検索、ドキュメント参照、オンライン検索など、コードナビゲーションに必要な機能を統合的に提供する。xref、dumb-jump、各種補完フレームワーク（ivy/helm/vertico）、Dashドキュメントなど複数のバックエンドを柔軟に組み合わせて使用できる。

**業務上の目的・背景**：
ソフトウェア開発において、コードの理解とナビゲーションは最も頻繁に行われる作業である。関数やクラスの定義を素早く参照し、その使用箇所を特定し、ドキュメントを確認することは、効率的な開発・デバッグに不可欠である。本モジュールは、これらの操作を統一されたインターフェースで提供し、言語やツールに依存しない一貫した開発体験を実現する。

**機能の利用シーン**：
- 関数呼び出し元から定義へジャンプ（+lookup/definition）
- シンボルの全使用箇所を検索（+lookup/references）
- APIドキュメントを即座に参照（+lookup/documentation）
- 不明な用語をオンラインで検索（+lookup/online）
- Dashドキュメントで詳細仕様を確認（+lookup/in-docsets）

**主要な処理内容**：
1. シンボル定義へのジャンプ（xref, dumb-jump, evil-goto-definition）
2. シンボル参照（使用箇所）の検索
3. 型定義へのジャンプ
4. 実装箇所の検索
5. ドキュメント参照（Dash docsets, オンライン）
6. ファイルパスの解決と開く
7. 辞書・シソーラス検索

**関連システム・外部連携**：
- xref：Emacs標準の定義ジャンプ
- dumb-jump：テキストベースの定義検索
- dash-docs：Dashドキュメントセット連携
- 各補完フレームワーク（ivy/helm/vertico）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | Vertico | 補助機能 | consult連携による検索・ジャンプ機能 |
| 5 | Ivy | 補助機能 | ivy-xref連携 |
| 6 | Helm | 補助機能 | helm-xref連携 |

## 機能種別

ナビゲーション / 検索 / ドキュメント参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| identifier | string | Yes | 検索対象のシンボル名 | 空文字列不可 |
| arg | prefix-arg | No | プレフィックス引数（ハンドラ選択用） | - |
| query | string | No | オンライン検索クエリ | - |
| provider | string | No | 検索プロバイダ名 | +lookup-provider-url-alist内の有効値 |

### 入力データソース

- ポイント位置のシンボル（doom-thing-at-point-or-region）
- +lookup-definition-functions（定義ジャンプハンドラリスト）
- +lookup-references-functions（参照検索ハンドラリスト）
- +lookup-documentation-functions（ドキュメントハンドラリスト）
- +lookup-provider-url-alist（オンライン検索プロバイダ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | marker/boolean | ジャンプ先位置またはジャンプ成否 |
| xrefs | list | xref結果リスト |

### 出力先

- バッファ（ジャンプ先）
- xref結果バッファ
- ブラウザ（オンライン検索時）
- Dashドキュメントウィンドウ

## 処理フロー

### 処理シーケンス

```
1. +lookup/definition コマンド呼び出し
   └─ ポイント位置のシンボル取得

2. ハンドラチェーン実行
   ├─ +lookup-dictionary-definition-backend-fn (text-mode)
   ├─ +lookup-xref-definitions-backend-fn (xref)
   ├─ +lookup-dumb-jump-backend-fn (dumb-jump)
   ├─ +lookup-project-search-backend-fn (ripgrep検索)
   └─ +lookup-evil-goto-definition-backend-fn (evil)

3. 結果処理
   ├─ ジャンプ成功: better-jumper でジャンプ履歴記録
   └─ 全ハンドラ失敗: エラーメッセージ表示
```

### フローチャート

```mermaid
flowchart TD
    A[+lookup/definition] --> B[identifier取得]
    B --> C{identifier有効?}
    C -->|No| X[エラー: Nothing under point]
    C -->|Yes| D[+lookup--jump-to :definition]
    D --> E{プレフィックス引数?}
    E -->|Yes| F[ハンドラ選択UI表示]
    E -->|No| G[ハンドラチェーン実行]
    F --> H[選択されたハンドラ実行]
    G --> I{ハンドラ成功?}
    H --> I
    I -->|Yes| J[better-jumper記録]
    I -->|No| K{次のハンドラあり?}
    K -->|Yes| G
    K -->|No| L[エラー: 定義が見つからない]
    J --> M[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ハンドラチェーン | ハンドラは順番に試行し、最初に成功したものを使用 | 常時 |
| BR-02 | 非同期ハンドラ後続抑止 | async指定のハンドラ以降は試行しない | :async t 指定時 |
| BR-03 | テキストモード辞書優先 | text-mode派生モードでは辞書検索を優先 | derived-mode-p 'text-mode |
| BR-04 | xref etags除外 | xref-backend-functionsからetags--xref-backendを除外 | 常時 |
| BR-05 | オンライン検索プロバイダ記憶 | 前回使用したプロバイダをモード別に記憶 | +lookup--last-provider |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Nothing under point | ポイント位置にシンボルがない | user-error表示 |
| - | 定義未発見 | 全ハンドラが失敗 | user-error表示 |
| - | ハンドラエラー | 個別ハンドラの実行時エラー | ログ出力、次ハンドラへ |

### リトライ仕様

リトライは行わない。ハンドラは順次試行され、失敗時は次のハンドラが試行される。

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

該当なし。

## パフォーマンス要件

- 定義ジャンプは1秒以内の応答を目標
- dumb-jumpはrg（ripgrep）を優先使用

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

- オンライン検索時、クエリはURLエンコードされる
- 外部ブラウザの起動は+lookup-open-url-fnに依存

## 備考

- +docsets フラグでDashドキュメント統合を有効化
- +dictionary フラグで辞書機能を有効化
- +offline フラグでオフライン辞書（wordnut）を使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/lookup/config.el` | +lookup-provider-url-alist の構造（17-48行目） |
| 1-2 | config.el | `modules/tools/lookup/config.el` | +lookup-definition-functions 等のハンドラリスト（53-120行目） |

**読解のコツ**:
- `+lookup-provider-url-alist`：`(name url-or-function ...)` 形式
- `+lookup-*-functions`：フック形式、run-hook-wrappedで実行

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | lookup.el | `modules/tools/lookup/autoload/lookup.el` | +lookup/definition コマンド（338-350行目） |

**主要処理フロー**:
1. **346行目**: doom-thing-at-point-or-region でシンボル取得
2. **348-349行目**: +lookup--jump-to で定義ジャンプ実行

#### Step 3: ハンドラ設定APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | lookup.el | `modules/tools/lookup/autoload/lookup.el` | set-lookup-handlers! マクロ（4-101行目） |

**主要処理フロー**:
- **69-101行目**: モードフックに初期化関数を登録
- **79-100行目**: :definition, :references等のハンドラをローカル変数に追加

#### Step 4: ジャンプ実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | lookup.el | `modules/tools/lookup/autoload/lookup.el` | +lookup--jump-to 関数（144-180行目） |
| 4-2 | lookup.el | `modules/tools/lookup/autoload/lookup.el` | +lookup--run-handlers 関数（121-142行目） |

**主要処理フロー**:
- **144-166行目**: プレフィックス引数による手動ハンドラ選択
- **166行目**: run-hook-wrapped でハンドラチェーン実行
- **177-178行目**: better-jumper でジャンプ履歴記録

#### Step 5: 各バックエンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | lookup.el | `modules/tools/lookup/autoload/lookup.el` | +lookup-xref-definitions-backend-fn（215-219行目） |
| 5-2 | lookup.el | `modules/tools/lookup/autoload/lookup.el` | +lookup-dumb-jump-backend-fn（227-238行目） |
| 5-3 | online.el | `modules/tools/lookup/autoload/online.el` | +lookup/online（27-59行目） |
| 5-4 | docsets.el | `modules/tools/lookup/autoload/docsets.el` | +lookup/in-docsets（78-101行目） |

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

```
+lookup/definition (identifier, arg)
    │
    └─ +lookup--jump-to (:definition, identifier, nil, arg)
           │
           ├─ [argあり] completing-read でハンドラ選択
           │
           └─ run-hook-wrapped (+lookup-definition-functions)
                  │
                  ├─ +lookup-dictionary-definition-backend-fn
                  │      └─ +lookup/dictionary-definition
                  │
                  ├─ +lookup-xref-definitions-backend-fn
                  │      └─ xref-backend-definitions
                  │
                  ├─ +lookup-dumb-jump-backend-fn
                  │      └─ dumb-jump-xref-activate
                  │
                  ├─ +lookup-project-search-backend-fn
                  │      └─ +ivy/helm/vertico-file-search
                  │
                  └─ +lookup-evil-goto-definition-backend-fn
                         └─ evil-goto-definition

結果処理:
+lookup--jump-to (続き)
    │
    ├─ [marker] switch-to-buffer & goto-char
    └─ better-jumper-set-jump (ジャンプ履歴)
```

### データフロー図

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

ポイント位置 ───▶ doom-thing-at-point-or-region ───▶ identifier
                           │
                           ▼
                  +lookup--jump-to
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
        xref          dumb-jump       project-search
           │               │               │
           └───────────────┴───────────────┘
                           │
                           ▼
                  ジャンプ先バッファ/位置
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/lookup/config.el` | ソース | 設定、ハンドラリスト定義 |
| lookup.el | `modules/tools/lookup/autoload/lookup.el` | ソース | 主要コマンド、ハンドラ実装 |
| online.el | `modules/tools/lookup/autoload/online.el` | ソース | オンライン検索 |
| docsets.el | `modules/tools/lookup/autoload/docsets.el` | ソース | Dashドキュメント連携 |
| evil.el | `modules/tools/lookup/autoload/evil.el` | ソース | Evil連携 |
| xwidget.el | `modules/tools/lookup/autoload/xwidget.el` | ソース | xwidget表示 |
| doctor.el | `modules/tools/lookup/doctor.el` | 診断 | 設定診断 |
| packages.el | `modules/tools/lookup/packages.el` | 設定 | 依存パッケージ定義 |
