# バッチ設計書 17-doc:source

## 概要

本ドキュメントは、CoffeeScriptプロジェクトにおける`doc:source`タスクの設計書です。このバッチは、doccoを使用してCoffeeScriptソースコードからアノテーション付きドキュメントを生成するツールです。

### 本バッチの処理概要

このバッチは、`src/`ディレクトリ配下のCoffeeScriptソースファイルに対して、doccoを実行し、コードとコメントを並べて表示するアノテーション付きソースドキュメントを生成します。生成されたHTMLは`docs/vX/annotated-source/`ディレクトリに出力されます。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解するためには、ソースコードを読む必要があります。doccoによるアノテーション付きドキュメントは、コードとその説明（コメント）を左右に並べて表示することで、コードの理解を大幅に支援します。これは、コントリビューターや言語実装に興味のある開発者にとって貴重なリソースとなります。

**バッチの実行タイミング**：手動実行、または`release`タスクの一部として実行されます。ソースコードの更新後やリリース準備時に実行します。

**主要な処理内容**：
1. `src/`ディレクトリに移動
2. doccoコマンドを実行し、全ての`*.*coffee`ファイルを処理
3. `--output ../docs/vX/annotated-source`オプションで出力先を指定
4. 各ソースファイルに対応するHTMLファイルを生成

**前後の処理との関連**：`release`タスクから呼び出されます。事前に`npm install`で`docco`パッケージがインストールされている必要があります。

**影響範囲**：`docs/vX/annotated-source/`ディレクトリにHTMLファイルが生成されます。

## バッチ種別

ドキュメント生成 / ソースコードドキュメント

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時・ソースコード更新時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動/releaseタスク |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.jsがインストールされていること |
| 依存パッケージ | `npm install`が完了していること（doccoを含む） |
| ソースファイル | src/配下にCoffeeScriptファイルが存在すること |

### 実行可否判定

- `src/`ディレクトリが存在すること
- `node_modules/docco/bin/docco`が存在すること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数なし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| src/*.coffee | CoffeeScript | コンパイラソースファイル |
| src/*.litcoffee | Literate CoffeeScript | 文芸的CoffeeScriptソースファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| docs/vX/annotated-source/*.html | HTML | アノテーション付きソースドキュメント |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 元のソースファイル名.html |
| 出力先 | docs/vX/annotated-source/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. generateAnnotatedSource関数実行
   └─ do構文で即時実行
2. doccoコマンド実行
   └─ cd src && ../node_modules/docco/bin/docco *.*coffee --output ...
3. 出力先ディレクトリ指定
   └─ ../docs/vX/annotated-source
4. 完了ログ出力
   └─ "generated annotated source in docs/vX/annotated-source/"
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[src/ディレクトリに移動]
    B --> C[doccoコマンド実行]
    C --> D[*.*coffeeファイル処理]
    D --> E[HTMLファイル生成]
    E --> F{エラー発生?}
    F -->|はい| G[例外スロー]
    F -->|いいえ| H[完了ログ出力]
    H --> I[バッチ終了]
    G --> I
```

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

### 操作別データベース影響一覧

該当なし（ファイルシステム操作のみ）

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コマンド実行エラー | doccoコマンドが見つからない | npm installを実行 |
| - | ファイル読み込みエラー | ソースファイルが存在しない | src/配下のファイルを確認 |

### リトライ仕様

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

### 障害時対応

- エラー発生時は例外がスローされる（`throw err if err`）
- doccoがインストールされていない場合は`npm install`を実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ソースファイル約10個 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

- 同時実行：可能だが推奨しない
- ロック仕様：なし

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 完了ログ | HTML出力完了時 | "generated annotated source in docs/vX/annotated-source/" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- doccoは外部ツールとして`node_modules/`配下にインストールされる
- `*.*coffee`パターンにより、`.coffee`と`.litcoffee`の両方が対象となる
- 出力されるHTMLはコードとコメントを左右2列で表示
- 各ソースファイルごとに個別のHTMLファイルが生成される
- `exec`関数で外部コマンドとして実行される
