# 通知設計書 8-doom-switch-buffer-hook

## 概要

本ドキュメントは、Doom Emacsにおける`doom-switch-buffer-hook`機能の設計を記載する。このフックは、バッファ切り替え時に登録された関数を実行するための通知メカニズムである。

### 本通知の処理概要

doom-switch-buffer-hookは、Emacsでバッファが切り替わった際に発火するカスタムフックである。パッケージや設定が、バッファ変更を検知して適切な処理を行うための拡張ポイントを提供する。

**業務上の目的・背景**：Emacsの標準フックでは、バッファ切り替えを直接検知する方法が限定的である。Doom Emacsでは、`window-buffer-change-functions`を活用して`doom-switch-buffer-hook`を実装し、バッファ切り替えに応じた処理（例：モードライン更新、シンタックスハイライト再計算、LSPクライアント切り替え等）を容易に実装できるようにしている。

**通知の送信タイミング**：`window-buffer-change-functions`がトリガーされた際に、`doom-run-switch-buffer-hooks-h`が呼び出され、`doom-switch-buffer-hook`が実行される。

**通知の受信者**：`doom-switch-buffer-hook`に登録された関数群。ユーザーコードやパッケージ設定から追加可能。

**通知内容の概要**：フック関数に引数は渡されない。現在のバッファは`(current-buffer)`で取得可能。

**期待されるアクション**：フック関数はバッファ切り替えに応じた処理（UIの更新、状態の同期など）を実行する。

## 通知種別

アプリ内通知（フック実行による内部通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | 無 |

### 送信先決定ロジック

`doom-switch-buffer-hook`に登録された全ての関数が順次実行される。

## 通知テンプレート

### フック実行の場合

| 項目 | 内容 |
|-----|------|
| 対象 | doom-switch-buffer-hookに登録された関数 |
| 引数 | なし |

### 本文テンプレート

該当なし（フック実行）

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| current-buffer | 現在のバッファ | (current-buffer)で取得 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | window-buffer-change-functions | 常に | バッファ変更検知 |
| 関数呼び出し | server-switch-hook | 常に | サーバー経由のファイルオープン |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | フックは常に実行される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[バッファ切り替え] --> B[window-buffer-change-functions発火]
    B --> C[doom-run-switch-buffer-hooks-h]
    C --> D[gc-cons-threshold最大化]
    D --> E[run-hooks 'doom-switch-buffer-hook]
    E --> F[各フック関数実行]
    F --> G[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（Emacs Lisp変数のみ使用）

### 変数参照詳細

| 変数名 | 用途 | 取得条件 |
|--------|------|---------|
| doom-switch-buffer-hook | フック関数リスト | 常時参照可能 |
| gc-cons-threshold | GC閾値 | 一時的にmost-positive-fixnumに設定 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| フック関数内エラー | フック関数の実装エラー | run-hooksにより伝播 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | バッファ切り替えごとに実行 |

### 配信時間帯

制限なし

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

- フック関数はローカルで実行され、外部通信はない
- パフォーマンス影響を考慮し、フック関数は軽量に実装すべき

## 備考

- `gc-cons-threshold`を一時的に最大化してGCによる遅延を防止
- `server-switch-hook`経由のファイルオープンにも対応
- Doom Emacsの初期化時に`doom-init-ui-h`でフックが設定される

---

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

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

### 推奨読解順序

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

フック変数の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | doom-ui.el | `lisp/doom-ui.el` | doom-switch-buffer-hook定義（90-91行目）を確認 |

**読解のコツ**: `defcustom`でカスタムフックを定義。ユーザーが関数を追加可能。

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

フック実行関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | doom-ui.el | `lisp/doom-ui.el` | doom-run-switch-buffer-hooks-h関数（105-108行目）を確認 |

**主要処理フロー**:
1. **105行目**: `doom-run-switch-buffer-hooks-h`関数定義
2. **106行目**: docstring「Trigger `doom-switch-buffer-hook' when selecting a new buffer.」
3. **107行目**: `gc-cons-threshold`を`most-positive-fixnum`に設定
4. **108行目**: `run-hooks 'doom-switch-buffer-hook`でフック実行

#### Step 3: フック登録処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | doom-ui.el | `lisp/doom-ui.el` | doom-init-ui-h関数（727-744行目）を確認 |
| 3-2 | doom-ui.el | `lisp/doom-ui.el` | フック登録（742-744行目）を確認 |

**主要処理フロー**:
- **742行目**: `window-buffer-change-functions`に`doom-run-switch-buffer-hooks-h`を追加
- **744行目**: `server-switch-hook`にも追加（サーバー経由対応）

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

```
[バッファ切り替え]
    |
    +-- window-buffer-change-functions
            |
            +-- doom-run-switch-buffer-hooks-h
                    |
                    +-- run-hooks 'doom-switch-buffer-hook
                            |
                            +-- [登録されたフック関数群]
```

### データフロー図

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

バッファ切り替え ──▶ window-buffer-change-functions
                              │
                              ▼
                    doom-run-switch-buffer-hooks-h
                              │
                              ▼
                    gc-cons-threshold最大化
                              │
                              ▼
                    run-hooks 'doom-switch-buffer-hook
                              │
                              ▼
                    [フック関数実行]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| doom-ui.el | `lisp/doom-ui.el` | ソース | doom-switch-buffer-hookの定義と実行処理 |
