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

## 概要

本ドキュメントは、CoffeeScript v2のビルドツールCakeモジュール（cake.coffee）のソースコード解説ページ「Annotated Source - Cake」の画面設計書です。Doccoツールによって生成された静的HTMLページとして、CoffeeScript用タスクランナーの実装詳細を解説しています。

### 本画面の処理概要

本画面は、CoffeeScript用のシンプルなビルドツール「Cake」を実装するcake.coffeeのソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：Cakeの内部動作を理解したい開発者向けに、Cakefileの読み込み・実行、task/option/invoke関数のグローバル公開、コマンドライン引数解析などの実装詳細を提供します。Make/Rake/Jakeに相当するCoffeeScript用タスクランナーの仕組みを学習でき、Cakefileの作成やカスタマイズの参考になります。

**画面へのアクセス方法**：v2ドキュメントページ（docs/v2/index.html）からAnnotated Sourceセクションへ遷移し、「cake.coffee」リンクをクリックしてアクセスします。または直接 docs/v2/annotated-source/cake.html にアクセスします。

**主要な操作・処理内容**：
1. ソースコードセクション（右側）と注釈セクション（左側）の並列表示を閲覧
2. 「Jump To」メニューから他のソースファイル解説ページへ遷移
3. セクションアンカーリンク（#section-N）によるページ内ナビゲーション
4. ハイライトされたCoffeeScriptコードの閲覧

**画面遷移**：
- 遷移元：v2ドキュメントページ、Annotated Source - Index
- 遷移先：browser.html, coffeescript.html, command.html, grammar.html, helpers.html, index.html, lexer.html, nodes.html, optparse.html, register.html, repl.html, rewriter.html, scope.html, sourcemap.html

**権限による表示制御**：特になし（静的HTMLページのため、すべてのユーザーが同一の内容を閲覧可能）

## 関連機能

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

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

本画面は静的HTMLページのため、ユーザー入力項目はありません。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| - | - | - | - |

## 表示項目

| 項目名 | 説明 | 表示位置 |
|--------|------|----------|
| タイトル | "cake.coffee" | ヘッダー部 |
| Jump Toメニュー | 他ソースファイルへのリンク一覧 | 右上ドロップダウン |
| セクション一覧 | コード解説セクション | メインコンテンツ |
| 注釈部 | 各セクションの解説テキスト | 左カラム |
| コード部 | シンタックスハイライト付きソースコード | 右カラム |

### 主要セクション内容

| セクションNo | 解説内容 |
|-------------|---------|
| 冒頭 | モジュール概要：Cakeの役割とMake/Rake/Jake比較 |
| 冒頭 | 外部依存関係（fs, path, helpers, optparse, CoffeeScript） |
| 冒頭 | CoffeeScript.register()の呼び出し |
| 中盤 | グローバル変数（tasks, options, switches, oparse） |
| 中盤 | task関数：タスク定義 |
| 中盤 | option関数：オプション定義 |
| 中盤 | invoke関数：タスク呼び出し |
| 中盤 | exports.run関数：Cake実行エントリーポイント |
| 終盤 | printTasks関数：タスク一覧表示 |
| 終盤 | fatalError/missingTask関数：エラー処理 |
| 終盤 | cakefileDirectory関数：Cakefile探索 |

## イベント仕様

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

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

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

各セクションの「#」リンクをクリックすると、そのセクションへのパーマリンクがURLハッシュに設定されます。

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

本画面は静的HTMLページのため、データベース操作はありません。

## メッセージ仕様

本画面にはユーザー操作に対するメッセージ表示機能はありません。

## 例外処理

本画面は静的HTMLページのため、アプリケーションレベルの例外処理はありません。HTTPレベルでの404エラー（ファイルが見つからない場合）はWebサーバーが処理します。

## 備考

- Doccoツールによって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- CoffeeScript自体のビルドにもCakefileが使用されている

---

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

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

### 推奨読解順序

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

Cakeのタスクとオプションの構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cake.coffee | `src/cake.coffee` | グローバル変数（tasks, options, switches）の構造を確認（20-23行） |

**読解のコツ**: tasksは{name: {name, description, action}}形式、switchesは[letter, flag, description]配列形式。

#### Step 2: グローバル関数を理解する

task/option/invoke関数がCakefileで使用される主要API です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cake.coffee | `src/cake.coffee` | helpers.extend globalでグローバル公開（26行） |
| 2-2 | cake.coffee | `src/cake.coffee` | task関数（30-32行） |
| 2-3 | cake.coffee | `src/cake.coffee` | option関数（37-38行） |
| 2-4 | cake.coffee | `src/cake.coffee` | invoke関数（41-43行） |

**主要処理フロー**:
1. **30-32行**: task(name, description, action) - tasksオブジェクトにタスクを登録
2. **37-38行**: option(letter, flag, description) - switchesに追加
3. **41-43行**: invoke(name) - 指定タスクのactionを実行

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

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

**主要処理フロー**:
- **50行**: __originalDirnameに現在ディレクトリを保存
- **51行**: Cakefileのあるディレクトリに移動
- **52行**: コマンドライン引数取得
- **53行**: Cakefileを読み込んでCoffeeScript.runで実行
- **54行**: OptionParserでオプション解析
- **55行**: 引数がなければprintTasks()
- **56-60行**: オプション解析とタスク実行

#### Step 4: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cake.coffee | `src/cake.coffee` | printTasks関数（63-72行） |
| 4-2 | cake.coffee | `src/cake.coffee` | cakefileDirectory関数（84-88行） |

**主要処理フロー**:
- **63-72行**: printTasks - rake -T形式でタスク一覧表示
- **84-88行**: cakefileDirectory - 親ディレクトリを再帰探索してCakefileを見つける

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

```
exports.run()
    |
    +-- cakefileDirectory(__originalDirname)
    |       |
    |       +-- fs.existsSync(path.join(dir, 'Cakefile'))
    |       +-- [再帰] cakefileDirectory(parent)
    |
    +-- process.chdir(cakefileDir)
    |
    +-- CoffeeScript.run(Cakefile内容)
    |       |
    |       +-- task(name, description, action) [グローバル]
    |       +-- option(letter, flag, description) [グローバル]
    |
    +-- new optparse.OptionParser(switches)
    |
    +-- [引数なし] printTasks()
    |       |
    |       +-- タスク一覧表示
    |
    +-- [引数あり] oparse.parse(args)
            |
            +-- invoke(arg) for arg in options.arguments
                    |
                    +-- tasks[name].action(options)
```

### データフロー図

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

Cakefile -------------> CoffeeScript.run ---------> task/option登録
                              |
                              v
                         tasksオブジェクト
                         switchesオブジェクト

process.argv ----------> OptionParser.parse ------> optionsオブジェクト
                              |
                              v
                         invoke(taskName)
                              |
                              v
                         tasks[name].action(options) -> タスク実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cake.coffee | `src/cake.coffee` | ソース | Cakeタスクランナー（89行） |
| cake.html | `docs/v2/annotated-source/cake.html` | テンプレート | 本画面のHTMLファイル |
| optparse.coffee | `src/optparse.coffee` | ソース | オプション解析（cake.coffeeで使用） |
| helpers.coffee | `src/helpers.coffee` | ソース | extend関数（グローバル公開用） |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | CoffeeScript.run関数 |
| Cakefile | `Cakefile` | 設定 | CoffeeScriptプロジェクトのビルドタスク定義 |
| bin/cake | `bin/cake` | 実行ファイル | Cake起動スクリプト |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
