# 画面設計書 23-Annotated Source - Cake

## 概要

本ドキュメントは、CoffeeScript v1のビルドツールCake(cake.coffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`cake.coffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。

**業務上の目的・背景**：CoffeeScriptプロジェクトのビルド自動化ツールであるCakeの内部実装を理解したい開発者向けに、Makeに似たタスクランナーの仕組みを解説する。cake.coffeeはCakefileに定義されたタスクを解析・実行するCLIツールで、task/option/invoke関数をグローバルスコープに提供する重要なモジュールである。

**画面へのアクセス方法**：v1 Annotated Sourceのインデックスページ(docs/v1/annotated-source/index.html)から「cake.coffee」リンクをクリック、またはURLを直接指定してアクセスする。

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. セクションアンカーリンクによる特定セクションへの直接アクセス
4. task、option、invoke関数の実装理解

**画面遷移**：
- 遷移元：v1 Annotated Source Index、他のAnnotated Sourceページ
- 遷移先：browser.coffee、coffee-script.coffee、command.coffee、grammar.coffee、helpers.coffee、index.coffee、lexer.coffee、nodes.coffee、optparse.coffee、register.coffee、repl.coffee、rewriter.coffee、scope.litcoffee、sourcemap.litcoffee

**権限による表示制御**：なし（静的ドキュメントのため全ユーザーがアクセス可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | Cakeタスクランナー | 主機能 | ビルドツールcake.coffeeのソースコード解説表示 |
| 43 | task関数 | 補助機能 | タスク定義関数の解説を含む |
| 44 | option関数 | 補助機能 | オプション定義関数の解説を含む |

## 画面種別

詳細（ソースコード解説ドキュメント）

## URL/ルーティング

`docs/v1/annotated-source/cake.html`

## 入出力項目

本画面は静的HTMLドキュメントのため、ユーザー入力項目はない。

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| タイトル | cake.coffee | h1テキスト |
| Jump Toメニュー | 他ソースファイルへの遷移リンク一覧 | ドロップダウンリスト |
| セクションリスト | ソースコード解説セクション（全12セクション） | 2カラムレイアウト |
| 解説テキスト | 各セクションの解説文 | HTML段落 |
| ソースコード | 対応するCoffeeScriptコード | シンタックスハイライト付きpre |

### 解説セクション一覧

| セクション番号 | 内容 | 対応する主要関数/処理 |
|----------------|------|----------------------|
| 1 | Cakeの概要とMake/Rake/Jake比較 | コメント |
| 2 | 外部依存モジュールインポート | fs, path, helpers, optparse, CoffeeScript |
| 3 | .coffee拡張子の登録 | CoffeeScript.register() |
| 4 | タスク・オプション管理変数 | tasks, options, switches, oparse |
| 5 | グローバルスコープへのmixin | helpers.extend global |
| 6 | task関数定義 | task: (name, description, action) |
| 7 | option関数定義 | option: (letter, flag, description) |
| 8 | invoke関数定義 | invoke: (name) |
| 9 | exports.run関数（メインエントリ） | Cakefile読み込み・実行 |
| 10 | printTasks関数 | タスク一覧表示 |
| 11 | fatalError/missingTask関数 | エラー処理 |
| 12 | cakefileDirectory関数 | Cakefile探索 |

## イベント仕様

### 1-Jump Toメニュークリック

ユーザーが「Jump To」メニューをクリックすると、ドロップダウンリストが展開され、他のソースファイル解説ページへのリンクが表示される。リンクをクリックすると対応するHTMLページに遷移する。

### 2-セクションアンカークリック

各セクションの段落記号（pilcrow）をクリックすると、そのセクションへのアンカーリンクがURLに設定され、ブックマークや共有に使用可能となる。

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

本画面は静的HTMLドキュメントであり、データベース操作は発生しない。

## メッセージ仕様

本画面は静的ドキュメントのため、動的メッセージは表示されない。

## 例外処理

静的HTMLファイルのため、以下のHTTPエラーのみ発生しうる：
- 404 Not Found: ファイルが見つからない場合
- 500 Internal Server Error: サーバー側の問題

## 備考

- Doccoツール（http://ashkenas.com/docco/）で自動生成されたドキュメント
- CoffeeScript 1.x系のソースコードを対象としている
- CakeはMake/Rake/Jakeに触発されたCoffeeScript用タスクランナー
- Cakefileというファイルにタスクを定義して使用する

---

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

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

### 推奨読解順序

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

cake.coffeeが管理する主要なデータ構造は、tasksオブジェクト（タスク定義）、switchesarray（オプション定義）、optionsオブジェクト（解析結果）である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cake.coffee | `src/cake.coffee` | 19-23行目のモジュールレベル変数を理解 |

**読解のコツ**: tasksオブジェクトは{name, description, action}の構造、switchesは[letter, flag, description]の配列であることを把握する。

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

cake.coffeeはcakeコマンド実行時にexports.runが呼び出される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cake.coffee | `src/cake.coffee` | 49-60行目のexports.run関数 |

**主要処理フロー**:
1. **50行目**: カレントディレクトリの保存
2. **51行目**: Cakefileが存在するディレクトリへ移動
3. **52行目**: コマンドライン引数の取得
4. **53行目**: CoffeeScript.runでCakefileを実行
5. **54行目**: OptionParserの初期化
6. **55行目**: 引数がなければタスク一覧表示
7. **56-59行目**: オプション解析
8. **60行目**: 各引数に対してinvoke実行

#### Step 3: task/option/invoke関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cake.coffee | `src/cake.coffee` | 30-32行目：task関数 |
| 3-2 | cake.coffee | `src/cake.coffee` | 37-38行目：option関数 |
| 3-3 | cake.coffee | `src/cake.coffee` | 41-43行目：invoke関数 |

**主要処理フロー**:
- **30-32行目**: task関数 - tasksオブジェクトにタスクを登録
- **37-38行目**: option関数 - switchesにオプション定義を追加
- **41-43行目**: invoke関数 - 指定タスクのaction関数を実行

#### Step 4: Cakefile探索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cake.coffee | `src/cake.coffee` | 84-88行目：cakefileDirectory関数 |

**主要処理フロー**:
- **85行目**: カレントディレクトリにCakefileがあれば返却
- **86行目**: 親ディレクトリを取得
- **87行目**: 親がルートでなければ再帰
- **88行目**: 見つからなければエラー

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

```
cakeコマンド実行
    |
    +-- exports.run()
            |
            +-- cakefileDirectory()  # Cakefile探索
            |
            +-- CoffeeScript.run(Cakefile)  # Cakefile実行
            |       |
            |       +-- task()     # グローバル関数としてタスク定義
            |       +-- option()   # グローバル関数としてオプション定義
            |
            +-- OptionParser.parse()  # コマンドライン解析
            |
            +-- printTasks()  # 引数なし時
            |       or
            +-- invoke(arg)   # 各タスク実行
                    |
                    +-- tasks[name].action(options)
```

### データフロー図

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

Cakefile              CoffeeScript.run()            tasksオブジェクト
                   --------->                           登録完了
                              |
                              v
                    task('name', 'desc', action)
                              |
                              v
                    tasks[name] = {name, desc, action}


コマンドライン引数     OptionParser.parse()          optionsオブジェクト
(cake build --watch)  --------->
                              |
                              v
                    invoke('build')
                              |
                              v
                    tasks['build'].action(options)  -----> タスク実行結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cake.coffee | `src/cake.coffee` | ソース | Cakeタスクランナーの実装 |
| cake.html | `docs/v1/annotated-source/cake.html` | テンプレート | Docco生成HTML |
| optparse.coffee | `src/optparse.coffee` | ソース | オプション解析 |
| helpers.coffee | `src/helpers.coffee` | ソース | ヘルパー関数（extend） |
| coffee-script.coffee | `src/coffee-script.coffee` | ソース | CoffeeScript.run使用 |
| docco.css | `docs/v1/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
| Cakefile | `Cakefile` | 設定 | プロジェクトのタスク定義 |
