# 通知設計書 4-display-warning通知

## 概要

本ドキュメントは、Doom Emacsにおける`display-warning`を使用した起動時エラー警告通知機能の設計を記載する。この通知は、システム設定ファイルの読み込みエラー時に警告を表示する機能である。

### 本通知の処理概要

display-warning通知は、Doom Emacsの起動プロセス中に発生したエラーをユーザーに通知するための機能である。特にプロファイル初期化ファイルの読み込み失敗時に使用される。

**業務上の目的・背景**：Doom Emacsの起動時には、ユーザー設定やモジュール設定など多くのファイルが読み込まれる。これらの読み込み中にエラーが発生すると、Emacsが正常に起動しない可能性がある。display-warning通知は、起動を完全に失敗させるのではなく、エラー情報を明確に表示してユーザーが問題を診断・修正できるようにする。

**通知の送信タイミング**：`doom-start.el`の`startup--load-user-init-file`アドバイス内で、初期化ファイルの読み込み中にエラーが発生した時点で警告が表示される。

**通知の受信者**：Emacsを起動しようとしているユーザー。`*Warnings*`バッファに記録され、ポップアップとしても表示される場合がある。

**通知内容の概要**：エラータイプ、エラーメッセージ、および問題解決のためのガイダンス（`--debug-init`オプションの使用推奨）が含まれる。

**期待されるアクション**：ユーザーは警告を確認し、`emacs --debug-init`で再起動して詳細なバックトレースを取得するか、設定ファイルを修正する。

## 通知種別

アプリ内通知（Emacs警告システム / `*Warnings*`バッファ）

## 送信仕様

### 基本情報

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

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

`display-warning`関数を使用し、`*Warnings*`バッファに記録。警告レベルは`:warning`。

## 通知テンプレート

### 警告メッセージの場合

| 項目 | 内容 |
|-----|------|
| 表示先 | *Warnings*バッファ |
| 警告タイプ | initialization |
| 警告レベル | :warning |
| 形式 | フォーマット済みテキスト |

### 本文テンプレート

```
An error occurred while booting Doom Emacs:

%s%s%s

To ensure normal operation, you should investigate and remove the
cause of the error in your Doom config files. Start Emacs with
the `--debug-init' option to view a complete error backtrace.
```

例：
```
An error occurred while booting Doom Emacs:

Wrong type argument: stringp, nil

To ensure normal operation, you should investigate and remove the
cause of the error in your Doom config files. Start Emacs with
the `--debug-init' option to view a complete error backtrace.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| error-type | エラータイプのメッセージ | (get (car error) 'error-message) | Yes |
| separator | エラー詳細がある場合の区切り | 条件分岐 | No |
| error-details | エラー詳細メッセージ | (cdr error) | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| エラー発生 | startup--load-user-init-file内でエラー | 常に | プロファイル初期化ファイル読み込み失敗 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| condition-case-unless-debug | debug-on-error時はデバッガ起動 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[startup--load-user-init-file開始] --> B[doom-profile-init-file取得]
    B --> C[ファイル読み込み試行]
    C --> D{エラー発生?}
    D -->|No| E[正常起動完了]
    D -->|Yes| F[エラー情報取得]
    F --> G[display-warning呼び出し]
    G --> H[*Warnings*バッファに記録]
    H --> I[init-file-had-error = t設定]
    I --> J[起動継続]
```

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

### 参照テーブル一覧

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

### 変数参照詳細

| 変数名 | 用途 | 取得条件 |
|--------|------|---------|
| doom-profile | 現在のプロファイル | 常時参照可能 |
| init-file-debug | デバッグ初期化フラグ | 起動時設定 |
| init-file-had-error | エラー発生フラグ | display-warning後にt設定 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 任意のerror | プロファイル初期化ファイル読み込み失敗 | display-warningで警告表示、起動継続 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | 起動時に1回のみ発生可能 |

### 配信時間帯

制限なし（起動時のみ）

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

- エラーメッセージにはファイルパスや設定内容が含まれる可能性がある
- *Warnings*バッファはローカルのみでアクセス可能
- バックトレースには内部実装詳細が含まれる

## 備考

- この機能は`doom-start.el`の`startup--load-user-init-file@init-doom`アドバイスで実装
- safe-modeプロファイルへのフォールバック機能がコメントアウトされている（将来実装予定）

---

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

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

### 推奨読解順序

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

起動プロセスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | doom.el | `lisp/doom.el` | doom-profileの定義（233-242行目）を確認 |

**読解のコツ**: `doom-profile`は`(NAME . VERSION)`形式のコンスセルで、現在のプロファイルを表す。

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

startup--load-user-init-fileアドバイスを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | doom-start.el | `lisp/doom-start.el` | startup--load-user-init-file@init-doom（298-361行目）を確認 |

**主要処理フロー**:
1. **298行目**: `define-advice`でアドバイス定義開始
2. **307行目**: `condition-case-unless-debug`でエラー捕捉開始
3. **318行目**: `doom-profile-init-file`でプロファイル初期化ファイルのパス取得
4. **340-353行目**: エラーハンドリングとdisplay-warning呼び出し
5. **341-352行目**: 警告メッセージのフォーマット

#### Step 3: 警告出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | doom-start.el | `lisp/doom-start.el` | display-warning呼び出し（341-352行目）を確認 |

**主要処理フロー**:
- **341行目**: `display-warning`関数呼び出し
- **342行目**: 警告タイプとして`'initialization`を指定
- **343-352行目**: `format-message`で警告本文を構築

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

```
startup--load-user-init-file (Emacsビルトイン)
    |
    +-- [アドバイス] startup--load-user-init-file@init-doom
            |
            +-- doom-profile-init-file (プロファイルファイルパス取得)
            |
            +-- doom-startup (実際の起動処理)
            |
            +-- [エラー発生時]
                    |
                    +-- display-warning
                            |
                            +-- *Warnings*バッファ出力
```

### データフロー図

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

doom-profile ──────▶ doom-profile-init-file ──▶ ファイルパス
                                                    │
                                                    ▼
                                              [ファイル読み込み]
                                                    │
                                              [エラー発生]
                                                    │
                                                    ▼
error オブジェクト ──▶ format-message ──▶ display-warning
                                                    │
                                                    ▼
                                          *Warnings*バッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| doom-start.el | `lisp/doom-start.el` | ソース | startup--load-user-init-fileアドバイスの定義 |
| doom.el | `lisp/doom.el` | ソース | doom-profileの定義 |
| doom-lib.el | `lisp/doom-lib.el` | ソース | doom-profile-init-file関数の定義 |
