# 画面設計書 22-HL Todo

## 概要

本ドキュメントは、Doom EmacsのHL Todo機能の画面設計について記述します。HL Todoは、コードコメント内のTODO、FIXME、NOTE等のキーワードを構文ハイライト表示する機能です。

### 本画面の処理概要

HL Todoは、プログラミングモードおよびYAMLモードにおいて、コメント内の特定のキーワード（TODO、FIXME、HACK等）を色分けハイライト表示する視覚支援機能を提供します。

**業務上の目的・背景**：ソフトウェア開発において、コード内に残された課題やメモを視覚的に目立たせることで、見落としを防止し、コードレビューや保守作業の効率を向上させます。チーム開発において、未完了タスク、既知のバグ、要検討事項などを一目で識別できるようにすることが目的です。

**画面へのアクセス方法**：HL Todoは自動的に有効化されるため、明示的な画面アクセスは不要です。以下のモードで自動的に有効化されます：
- prog-mode（すべてのプログラミングモードの親モード）
- yaml-mode

**主要な操作・処理内容**：
1. prog-modeまたはyaml-modeのバッファを開く
2. hl-todo-modeが自動的に有効化される
3. コメント内のキーワードが正規表現でマッチされる
4. マッチしたキーワードに対応するフェイス（色・スタイル）が適用される
5. `]t` / `[t` キーバインドでTODOアイテム間を移動可能

**画面遷移**：HL Todoは独立した画面ではなく、編集バッファ上で動作する視覚エフェクトです。他の画面への遷移機能はありませんが、`SPC s p`（プロジェクト検索）や`SPC s b`（バッファ検索）と組み合わせてTODOキーワードを検索できます。

**権限による表示制御**：権限による制御はありません。すべてのユーザーに同一の表示が提供されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | TODO/FIXME等のハイライト表示 | 主機能 | タスクキーワードの強調表示 |

## 画面種別

視覚エフェクト（構文ハイライト）

## URL/ルーティング

N/A（Emacsバッファ上で動作するため、URLの概念なし）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|----------|------|
| hl-todo-keyword-faces | 入力 | alist | キーワードとフェイスの対応定義 |
| hl-todo-highlight-punctuation | 入力 | string | ハイライト対象に含める句読点 |
| hl-todo-regexp | 内部 | string | キーワードマッチ用正規表現 |

## 表示項目

| 項目 | 説明 | 表示スタイル |
|------|------|-------------|
| TODO | 後日対応が必要なリマインダー | warning + bold（警告色、太字） |
| FIXME | 既知の問題、未実装、遅い処理 | error + bold（エラー色、太字） |
| REVIEW | 後で見直し、改善、非重大問題 | font-lock-keyword-face + bold |
| HACK | 意図的な問題のあるコード | font-lock-constant-face + bold |
| DEPRECATED | 廃止予定のコード | font-lock-doc-face + bold |
| NOTE | 重要な実装の注意点 | success + bold（成功色、太字） |
| BUG | ワークアラウンドが必要な既知バグ | error + bold（エラー色、太字） |
| XXX | 問題のある/誤解を招くコード警告 | font-lock-constant-face + bold |

## イベント仕様

### 1-モード有効化

prog-modeまたはyaml-modeのバッファを開いた際にhl-todo-modeが自動的に有効化されます。

**処理フロー**：
1. prog-mode-hookまたはyaml-mode-hookが発火
2. `hl-todo-mode` が呼び出される
3. `hl-todo-keyword-faces` に基づいて正規表現が生成される
4. `font-lock-keywords` にキーワードパターンが追加される
5. バッファ内のキーワードがハイライト表示される

### 2-TODOアイテム間ナビゲーション

キーバインドを使用してTODOアイテム間を移動できます。

**処理フロー**：
1. `]t` または `[t` キーを押下
2. 次/前のTODOキーワードを検索
3. カーソルをキーワード位置に移動

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

N/A（データベースを使用しない）

## メッセージ仕様

N/A（メッセージ表示なし）

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| pug-mode/haml-mode | フェイス検出ベースの代替検出方法を使用 |
| args-out-of-range エラー | font-lock-fontify-region のパラメータをクランプ |

## 備考

- hl-todo-keyword-facesをカスタマイズして独自のキーワードを追加可能
- コメント構文テーブルが不完全なモード（pug-mode、haml-mode）では代替検出方法を使用
- `:` をhl-todo-highlight-punctuationに設定することで、`TODO:` のような形式も認識

---

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

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

### 推奨読解順序

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

キーワードとフェイスのマッピングが中心的なデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/hl-todo/config.el` | `hl-todo-keyword-faces` の定義を確認（行8-28） |

**読解のコツ**: `hl-todo-keyword-faces` はalistで、各要素は `(キーワード文字列 . フェイス定義)` の形式です。フェイス定義には既存フェイス名やシンボル、属性リストを指定できます。

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

モードフックによる自動有効化がエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/hl-todo/config.el` | `:hook` ディレクティブによるモード登録（行4-5） |

**主要処理フロー**:
1. **行4**: `prog-mode` フックに `hl-todo-mode` を登録
2. **行5**: `yaml-mode` フックに `hl-todo-mode` を登録
3. **行7-28**: `hl-todo-highlight-punctuation` と `hl-todo-keyword-faces` の設定

#### Step 3: 例外処理を理解する

特定のモードでの代替検出方法の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/hl-todo/config.el` | adviceとフック処理（行31-51） |

**主要処理フロー**:
- **行31-36**: `+hl-todo-clamp-font-lock-fontify-region-a` - args-out-of-rangeエラー対策のadvice
- **行40-51**: `+hl-todo--use-face-detection-h` - pug-mode/haml-mode用の代替キーワード検出

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

```
バッファオープン
    │
    ├─ prog-mode-hook ────────────────────┐
    │                                      │
    └─ yaml-mode-hook ────────────────────┼──▶ hl-todo-mode
                                           │         │
                                           │         ▼
                                           │   font-lock-keywords 更新
                                           │         │
                                           │         ▼
                                           │   キーワードハイライト表示
                                           │
    ├─ pug-mode-hook ─────────────────────┤
    │                                      │
    └─ haml-mode-hook ────────────────────┼──▶ +hl-todo--use-face-detection-h
                                                      │
                                                      ▼
                                               hl-todo-keywords 書き換え
                                                      │
                                                      ▼
                                               hl-todo-mode 再起動
```

### データフロー図

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

バッファテキスト ───▶ hl-todo-regexp マッチ ───▶ ハイライト表示
                              │
                              ├─ キーワード: "TODO"
                              ├─ キーワード: "FIXME"
                              ├─ キーワード: "HACK"
                              └─ ...

hl-todo-keyword-faces ───▶ フェイス適用 ───▶ 色・スタイル変更
       │
       └─ ("TODO" warning bold)
       └─ ("FIXME" error bold)
       └─ ("NOTE" success bold)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/hl-todo/config.el` | ソース | パッケージ設定、キーワード定義、例外処理 |
| packages.el | `modules/ui/hl-todo/packages.el` | 設定 | hl-todoパッケージの依存定義 |
| README.org | `modules/ui/hl-todo/README.org` | ドキュメント | モジュール説明書、使用方法 |
| .doommodule | `modules/ui/hl-todo/.doommodule` | 設定 | Doomモジュールメタデータ |
