# 機能設計書 28-TODO/FIXME等のハイライト表示

## 概要

本ドキュメントは、Doom EmacsにおけるTODO/FIXME等のハイライト表示機能の設計を記述する。hl-todoパッケージを使用し、コード内のTODO、FIXME、HACK等のタスクキーワードを視覚的に強調表示することで、未完了タスクや要修正箇所の発見を容易にする。

### 本機能の処理概要

**業務上の目的・背景**：開発者がコード内に残したタスクマーカー（TODO、FIXME等）を見落とさないよう、視覚的に強調表示する。これにより、コードレビュー時や保守作業時に未完了タスクや問題箇所を素早く特定できる。

**機能の利用シーン**：プログラミング時のタスク管理、コードレビュー、技術的負債の可視化、将来の改善箇所のマーキング。

**主要な処理内容**：
1. prog-modeおよびyaml-modeでのhl-todo-mode有効化
2. キーワード（TODO、FIXME、HACK等）の検出
3. キーワードごとの色分け表示
4. コロン記号（:）を含むキーワードの強調

**関連システム・外部連携**：hl-todoパッケージとの連携。

**権限による制御**：本機能は全ユーザーが利用可能であり、権限による制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | HL Todo | 主機能 | タスクキーワードの強調表示 |

## 機能種別

UI表示 / シンタックスハイライト

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| hl-todo-highlight-punctuation | string | No | ハイライト対象の句読点（デフォルト: ":"） | 文字列 |
| hl-todo-keyword-faces | alist | No | キーワードとフェイスのマッピング | alistフォーマット |

### 入力データソース

- バッファ内のソースコードテキスト
- コメント領域内のキーワード

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ハイライト表示 | face | キーワードに適用されるフェイス（色、太字等） |

### 出力先

- バッファ内のテキスト表示（フェイス適用）

## 処理フロー

### 処理シーケンス

```
1. prog-mode-hookまたはyaml-mode-hookの実行
   └─ hl-todo-mode有効化
2. バッファ内キーワードの検出
   └─ hl-todo-keyword-facesに基づくパターンマッチ
3. フェイスの適用
   └─ キーワードごとの色分け表示
```

### フローチャート

```mermaid
flowchart TD
    A[prog-mode/yaml-mode有効化] --> B[hl-todo-mode有効化]
    B --> C[バッファスキャン]
    C --> D{キーワード検出}
    D -->|TODO| E[warning face適用]
    D -->|FIXME| F[error face適用]
    D -->|HACK| G[constant face適用]
    D -->|NOTE| H[success face適用]
    E --> I[ハイライト表示]
    F --> I
    G --> I
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-28-01 | prog-mode有効化 | prog-modeでhl-todo-modeを自動有効化 | prog-mode-hook |
| BR-28-02 | yaml-mode有効化 | yaml-modeでhl-todo-modeを自動有効化 | yaml-mode-hook |
| BR-28-03 | キーワードフェイス | キーワードごとに異なるフェイスを適用 | キーワード検出時 |
| BR-28-04 | コロン含有 | キーワード後のコロン（:）もハイライト対象 | hl-todo-highlight-punctuation |

### キーワードとフェイスの対応

| キーワード | フェイス | 用途 |
|-----------|---------|------|
| 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 | 注意が必要なコード |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERR-28-01 | args-out-of-range | 一部モードでfont-lock-fontify-regionがエラー | +hl-todo-clamp-font-lock-fontify-region-aでクランプ処理 |

### リトライ仕様

リトライ処理は実装されていない

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

該当なし

## パフォーマンス要件

- フォントロック機構に統合されており、パフォーマンス影響は軽微

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

- 表示機能のみであり、セキュリティリスクなし

## 備考

- pug-modeとhaml-modeでは、構文テーブルの問題により異なる検出方法を使用
- face-based検出では、font-lock-comment-faceを持つテキスト内のみを検索

---

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

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

### 推奨読解順序

#### Step 1: 設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/hl-todo/config.el` | hl-todoパッケージの設定 |
| 1-2 | packages.el | `modules/ui/hl-todo/packages.el` | パッケージ依存定義 |

**読解のコツ**: hl-todo-keyword-facesのalistフォーマットを理解する。各キーワードに対して`(face1 face2 ...)`形式でフェイスを指定。

**主要処理フロー**:
- **3行目**: `use-package! hl-todo` - hl-todoパッケージの設定開始
- **4-5行目**: prog-modeとyaml-modeでのフック登録
- **7-8行目**: hl-todo-highlight-punctuationの設定
- **8-28行目**: hl-todo-keyword-facesの定義（各キーワードの意味とフェイス）
- **31-36行目**: args-out-of-rangeエラー対策のアドバイス
- **40-51行目**: pug-mode/haml-modeでの代替検出方法

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

```
prog-mode-hook / yaml-mode-hook
    │
    └─ hl-todo-mode
           │
           ├─ hl-todo-keyword-faces (キーワード定義)
           │
           ├─ font-lock-fontify-region
           │      └─ +hl-todo-clamp-font-lock-fontify-region-a (アドバイス)
           │
           └─ hl-todo-keywords (特殊モード用)
                  └─ +hl-todo--use-face-detection-h
```

### データフロー図

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

バッファテキスト ───▶ hl-todo-mode ───▶ キーワード検出
                                            │
hl-todo-keyword-faces ─────────────────────▶ フェイス適用
                                            │
                                            ▼
                                      ハイライト表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/hl-todo/config.el` | ソース | メイン設定ファイル |
| packages.el | `modules/ui/hl-todo/packages.el` | 設定 | パッケージ依存定義 |
