# 通知設計書 7-errRstMissingClosing

## 概要

本ドキュメントは、Nimコンパイラにおけるエラー通知「errRstMissingClosing」の設計仕様を定義する。

### 本通知の処理概要

errRstMissingClosingは、reStructuredText（RST）またはMarkdownドキュメントのパース中に、閉じタグ・括弧・引用符などの終端記号が不足している場合に出力されるエラー通知である。

**業務上の目的・背景**：Nimコンパイラはソースコード内のドキュメントコメント（##で始まるコメント）をRSTまたはMarkdown形式でパースし、ドキュメントを生成する。マークアップ構文には開始タグと終了タグの対応が必要であり、閉じタグが不足している場合、ドキュメントの正確な解釈ができないため、開発者に問題を通知する必要がある。

**通知の送信タイミング**：RSTまたはMarkdownパーサー（lib/packages/docutils/rst.nim）がドキュメントを解析中に、対応する閉じ記号が見つからない場合に発行される。docgen.nimのcompilerMsgHandler経由で変換される。

**通知の受信者**：Nimソースコードをコンパイルしている開発者、またはRST/Markdownドキュメントを作成している開発者。ドキュメント記法の修正が必要。

**通知内容の概要**：エラー詳細メッセージ（$1）として、不足している閉じ記号の情報が出力される。メッセージテンプレートは単純に"$1"であり、具体的な内容はパーサーから渡される。

**期待されるアクション**：開発者は、エラーメッセージで指摘された位置を確認し、対応する閉じ記号（括弧、引用符、バッククォートなど）を追加することが期待される。

## 通知種別

コンパイラ標準出力/標準エラー出力（コンソール通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高（Error） |
| リトライ | なし |

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

コンパイラオプション`--stdout`が指定されている場合はstdoutに、それ以外はstderrに出力される。

## 通知テンプレート

### コンソール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | Nimコンパイラ |
| メッセージ種別 | Error |
| 形式 | テキスト |

### 本文テンプレート

```
{ファイル名}({行},{列}) Error: {詳細メッセージ}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | エラー詳細メッセージ | RSTパーサーからのメッセージ | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| RSTパース処理 | meMissingClosingイベント | 閉じ記号不足検出 | rst.nim |
| ドキュメント生成 | メッセージ変換 | meKindマッピング | docgen.nim 249行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| errorsAsWarnings有効時 | roPreferMarkdownかつ非standaloneDocの場合、警告として扱われる |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[RSTドキュメントパース] --> B{閉じ記号検出}
    B -->|存在| C[処理継続]
    B -->|不足| D[meMissingClosing発行]
    D --> E[compilerMsgHandler]
    E --> F[errRstMissingClosingへ変換]
    F --> G{errorsAsWarnings?}
    G -->|Yes| H[警告として出力]
    G -->|No| I[globalError呼び出し]
    I --> J[メッセージ出力]
```

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

### 参照テーブル一覧

該当なし（ファイルベースの処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 引用符不足 | 開始引用符に対応する終了引用符がない | 終了引用符を追加 |
| 括弧不足 | 開始括弧に対応する終了括弧がない | 終了括弧を追加 |
| バッククォート不足 | インラインコードの終了記号がない | 終了バッククォートを追加 |
| ディレクティブ不正 | RST構文の終端が見つからない | 構文を修正 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

- エラーメッセージにはドキュメント内容の一部が含まれる可能性がある
- ファイルパス情報が含まれる
- ローカル開発環境での使用を想定

## 備考

- errRstMissingClosingはエラー（Error）カテゴリに属する
- メッセージテンプレートは"$1"のみで、詳細はRSTパーサーから提供される
- roPreferMarkdownオプションとstandaloneDocフラグにより、警告として扱われる場合がある
- 警告扱いの場合、raiseRecoverableErrorでパースを中断し、モノスペーステキストとして出力される

---

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

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

### 推奨読解順序

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

errRstMissingClosing通知の基盤となるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型でerrRstMissingClosingの定義を確認（36行目） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | MsgKindToStr配列でメッセージ文字列を確認（127行目） |

**読解のコツ**: errRstMissingClosingは非致命的エラーセクションのRST関連エラーの最初に定義されている。メッセージテンプレートは"$1"のみ。

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

通知発行の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | docgen.nim | `compiler/docgen.nim` | compilerMsgHandlerでのメッセージ変換（241-277行目） |
| 2-2 | docgen.nim | `compiler/docgen.nim` | meMissingClosingからerrRstMissingClosingへのマッピング（249行目） |

**主要処理フロー**:
1. **249行目**: `of meMissingClosing: k = errRstMissingClosing`
2. **268-275行目**: errorsAsWarnings判定と処理分岐

#### Step 3: エラー処理モードを理解する

警告として扱う場合の処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | docgen.nim | `compiler/docgen.nim` | errorsAsWarnings条件（268-269行目） |
| 3-2 | docgen.nim | `compiler/docgen.nim` | raiseRecoverableError呼び出し（275行目） |

**主要処理フロー**:
- **268行目**: `roPreferMarkdown in d.sharedState.options`かつ`not d.standaloneDoc`
- **270-272行目**: 警告として出力しignoreError=true
- **275行目**: パースを中断してモノスペーステキストにフォールバック

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

```
RST/Markdownパーサー (lib/packages/docutils/rst.nim)
    │
    └─ meMissingClosingイベント発行
           │
           └─ compilerMsgHandler(filename, line, col, meMissingClosing, arg)
                  │
                  └─ case msgKind of meMissingClosing: k = errRstMissingClosing
                         │
                         ├─ errorsAsWarnings = true
                         │      └─ liMessage(..., ignoreError=true)
                         │             └─ raiseRecoverableError("")
                         │
                         └─ errorsAsWarnings = false
                                └─ globalError(conf, info, errRstMissingClosing, arg)
```

### データフロー図

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

RST/MDソース ────▶ RSTパーサー ────────────▶ 標準エラー出力
                    │                         "{詳細メッセージ}"
                    ▼
               meMissingClosing
                    │
                    ▼
               compilerMsgHandler
                    │
                    ▼
               errRstMissingClosing
                    │
                    ▼
               globalError/liMessage
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind定義、メッセージ文字列定義 |
| docgen.nim | `compiler/docgen.nim` | ソース | compilerMsgHandler、メッセージ変換 |
| rst.nim | `lib/packages/docutils/rst.nim` | ソース | RSTパーサー本体 |
| msgs.nim | `compiler/msgs.nim` | ソース | globalError/liMessage関数 |
