# 画面設計書 29-Annotated Source - Scope (v2)

## 概要

本ドキュメントは、CoffeeScript v2のスコープ管理(scope.litcoffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`scope.litcoffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。scope.litcoffeeはLiterate CoffeeScript形式で書かれており、変数のスコープ管理を担当する。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解したい開発者向けに、変数スコープの管理方法を解説する。Scopeクラスはコード生成時に変数宣言を追跡し、どの変数が新規でvar宣言が必要か、どの変数が外部スコープと共有されているかを管理する。これにより適切なJavaScript変数宣言が生成される。

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

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. Scopeクラスと変数管理メソッドの実装理解
4. スコープチェーンと変数解決の仕組み理解

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | スコープ管理 | 主機能 | スコープ管理scope.litcoffeeのソースコード解説表示（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

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

### 主要メソッド

| メソッド名 | 説明 | 処理内容 |
|------------|------|---------|
| constructor | コンストラクタ | 親スコープ、変数リスト初期化 |
| add | 変数追加 | 変数をスコープに登録 |
| namedMethod | 名前付きメソッド探索 | super呼び出し用 |
| find | 変数検索・宣言 | 変数存在確認、なければ宣言 |
| parameter | パラメータ登録 | 関数引数をスコープに登録 |
| check | 変数存在確認 | スコープチェーンで検索 |
| temporary | 一時変数名生成 | _var, _var2等 |
| type | 変数タイプ取得 | var/param/arguments等 |
| freeVariable | 空き変数名取得 | 未使用の一時変数名 |
| assign | 代入式登録 | スコープ先頭での代入 |
| hasDeclarations | 宣言有無 | var宣言が必要か |
| declaredVariables | 宣言変数リスト | var宣言対象一覧 |
| assignedVariables | 代入変数リスト | 代入式一覧 |

## イベント仕様

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

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

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

各セクションの段落記号をクリックすると、そのセクションへのアンカーリンクがURLに設定される。

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールで自動生成されたドキュメント
- CoffeeScript 2.x系のソースコードを対象
- Literate CoffeeScript形式（.litcoffee）で記述
- nodes.coffeeのCodeノードから使用される

---

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

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

### 推奨読解順序

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

Scopeクラスが管理するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | scope.litcoffee | `src/scope.litcoffee` | variables配列の構造 |
| 1-2 | scope.litcoffee | `src/scope.litcoffee` | positions/commentsオブジェクト |

**読解のコツ**: variables配列は{name, type}オブジェクトの配列。typeは'var'/'param'/'arguments'等。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | scope.litcoffee | `src/scope.litcoffee` | constructorがエントリーポイント |

**主要処理フロー**:
1. **constructor**: @parent, @expressions, @method, @referencedVars受け取り
2. **variables初期化**: argumentsを初期登録
3. **@root設定**: ルートスコープへの参照

#### Step 3: 変数操作メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | scope.litcoffee | `src/scope.litcoffee` | add - 変数追加 |
| 3-2 | scope.litcoffee | `src/scope.litcoffee` | find - 検索・宣言 |
| 3-3 | scope.litcoffee | `src/scope.litcoffee` | check - 存在確認 |

**主要処理フロー**:
- **add(name, type)**: positionsで位置管理、variablesに追加
- **find(name)**: check後、なければadd
- **check(name)**: 自スコープ→親スコープと検索

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

```
Code.compileNode()  (nodes.coffee)
    |
    +-- new Scope(@parent, @expressions, @method)
            |
            +-- 変数操作
            |       |
            |       +-- add(name, type)
            |       +-- find(name)
            |       +-- parameter(name)
            |       +-- freeVariable(name)
            |
            +-- 宣言生成
                    |
                    +-- hasDeclarations()
                    +-- declaredVariables()
                    +-- assignedVariables()
```

### データフロー図

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

CoffeeScriptコード    Scope操作                   JavaScript var宣言
(関数定義)         --------->
                            |
                            v
               変数参照を検出 -> add()
                            |
                            v
               declaredVariables() -----> var x, y, z;
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| scope.litcoffee | `src/scope.litcoffee` | ソース | スコープ管理 |
| scope.html | `docs/v2/annotated-source/scope.html` | テンプレート | Docco生成HTML |
| nodes.coffee | `src/nodes.coffee` | ソース | Scopeを使用 |
| docco.css | `docs/v2/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
