# 画面設計書 11-Annotated Source - Nodes

## 概要

本ドキュメントは、CoffeeScript v1のソースコード解説ページ「Annotated Source - Nodes」の画面設計書である。Doccoを使用して自動生成されたドキュメントページで、nodes.coffeeのソースコードとその解説を並列表示する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの中核である構文木（AST: Abstract Syntax Tree）ノードクラス群を定義するnodes.coffeeのソースコードを、コメントと実装コードを並列表示する形式で解説するドキュメントページである。

**業務上の目的・背景**：CoffeeScriptの開発者やコントリビューターが、コンパイラの内部実装を理解するために必要な画面である。特に、CoffeeScriptコードがどのようにJavaScriptに変換されるかを理解するには、各ASTノードの構造と役割を把握することが不可欠である。本画面により、ソースコードを読みながら設計思想や実装の意図を同時に学ぶことができる。

**画面へのアクセス方法**：v1ドキュメントページ（docs/v1/index.html）のAnnotated Sourceセクション、またはAnnotated Source - Index（docs/v1/annotated-source/index.html）から「nodes.coffee」リンクをクリックしてアクセスする。直接URL（docs/v1/annotated-source/nodes.html）でもアクセス可能である。

**主要な操作・処理内容**：
1. ソースコードとコメントの並列表示を閲覧する
2. 「Jump To...」メニューから他のソースファイル解説ページへ遷移する
3. セクション番号リンク（pilcrow）をクリックして特定のコードセクションへの直接リンクを取得する
4. ページ内スクロールで各クラス定義（CodeFragment、Base、Block、Literal、Value等）の解説を確認する

**画面遷移**：
- 遷移元: v1ドキュメント（docs/v1/index.html）、Annotated Source - Index（docs/v1/annotated-source/index.html）、他のAnnotated Sourceページ
- 遷移先: Jump Toメニューから他のすべてのAnnotated Sourceページ（browser.coffee、cake.coffee、coffee-script.coffee、command.coffee、grammar.coffee、helpers.coffee、index.coffee、lexer.coffee、optparse.coffee、register.coffee、repl.coffee、rewriter.coffee、scope.litcoffee、sourcemap.litcoffee）

**権限による表示制御**：本画面は静的HTMLファイルであり、認証・認可の仕組みは存在しない。すべてのユーザーが同一の内容を閲覧できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | Nodes | 主機能 | 構文木ノードクラスnodes.coffeeのソースコード解説表示 |
| 18 | コードフラグメント | 補助機能 | CodeFragmentクラスの解説を含む |

## 画面種別

詳細（ドキュメント閲覧画面）

## URL/ルーティング

- URL: `/docs/v1/annotated-source/nodes.html`
- 静的HTMLファイルとして配置

## 入出力項目

本画面は静的HTMLであり、ユーザー入力項目は存在しない。

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| - | - | - | - | 入力項目なし |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ページタイトル | テキスト | "nodes.coffee" |
| ソースコード | HTML（ハイライト済み） | nodes.coffeeの全ソースコード |
| コメント/解説 | HTML | 各コードセクションに対応する解説テキスト |
| Jump Toメニュー | リンクリスト | 他のソースファイルへのナビゲーション |
| セクションリンク | アンカーリンク | 各セクションへの直接リンク（#section-N形式） |

## イベント仕様

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

Jump Toリンクをクリックすると、対応するソースコード解説ページへ遷移する。

- イベントタイプ: クリック
- 対象要素: `#jump_to a.source`
- 処理内容: 指定されたHTMLファイルへのページ遷移

### 2-セクションリンククリック

各セクションの段落記号（pilcrow: &#182;）をクリックすると、そのセクションへの直接リンクがブラウザのURLバーに表示される。

- イベントタイプ: クリック
- 対象要素: `a.pilcrow`
- 処理内容: URLハッシュの変更（#section-N）

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

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

本画面は静的HTMLファイルであり、データベース操作は発生しない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベース操作なし |

## メッセージ仕様

本画面は静的HTMLであり、動的なメッセージ表示機能は存在しない。

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | - | - | - |

## 例外処理

本画面は静的HTMLであり、アプリケーションレベルの例外処理は存在しない。
- HTTPレベル: 404 Not Found（ファイルが存在しない場合）
- HTTPレベル: 500 Internal Server Error（サーバー設定エラー等）

## 備考

- 本画面はDoccoツールによって自動生成されたHTMLファイルである
- ソースコードはsrc/nodes.coffeeから生成される
- スタイルシートはdocco.cssを使用
- レスポンシブデザイン対応（viewport設定あり）
- v2系にも同様のページ（docs/v2/annotated-source/nodes.html）が存在する

---

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

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

### 推奨読解順序

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

まず、nodes.coffeeで定義される主要なデータ構造（ASTノードクラス）を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nodes.coffee | `src/nodes.coffee` | CodeFragmentクラス（行33-42）：コード生成の基本単位 |
| 1-2 | nodes.coffee | `src/nodes.coffee` | Baseクラス（行59以降）：すべてのASTノードの基底クラス |

**読解のコツ**: CoffeeScriptのクラス構文を理解しておくこと。`class X extends Y`の形式で継承関係が定義される。

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

HTMLファイルの構造と、Doccoによる生成プロセスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nodes.html | `docs/v1/annotated-source/nodes.html` | 生成されたHTMLの構造、セクション分割 |

**主要処理フロー**:
1. **行1-10**: HTMLヘッダー、メタ情報、スタイルシート読み込み
2. **行11-100**: Jump Toナビゲーションメニュー
3. **行102以降**: ソースコードとコメントの並列表示セクション

#### Step 3: 関連モジュールを理解する

nodes.coffeeが依存する他のモジュールとの関係を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | scope.litcoffee | `src/scope.litcoffee` | Scopeクラス：変数スコープ管理 |
| 3-2 | helpers.coffee | `src/helpers.coffee` | ヘルパー関数群：compact、flatten、extend等 |
| 3-3 | lexer.coffee | `src/lexer.coffee` | isUnassignable、JS_FORBIDDEN：予約語チェック |

**主要処理フロー**:
- **nodes.coffee 行8**: `{Scope} = require './scope'` でスコープ管理クラスをインポート
- **nodes.coffee 行9**: `{isUnassignable, JS_FORBIDDEN} = require './lexer'` で予約語チェック関数をインポート
- **nodes.coffee 行12-15**: helpers.coffeeから各種ユーティリティ関数をインポート

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

```
nodes.html (生成されたHTML)
    |
    +-- nodes.coffee (ソースファイル)
           |
           +-- scope.litcoffee
           |      +-- Scope クラス
           |
           +-- lexer.coffee
           |      +-- isUnassignable
           |      +-- JS_FORBIDDEN
           |
           +-- helpers.coffee
                  +-- compact
                  +-- flatten
                  +-- extend
                  +-- merge
                  +-- del
                  +-- starts
                  +-- ends
                  +-- some
                  +-- addDataToNode
                  +-- attachCommentsToNode
                  +-- locationDataToString
                  +-- throwSyntaxError
```

### データフロー図

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

src/nodes.coffee     --->   Docco (ドキュメント生成ツール)   --->   docs/v1/annotated-source/nodes.html
       |                           |
       |                           +-- コメント抽出
       |                           +-- コードハイライト
       |                           +-- HTML生成
       |
       +-- CoffeeScriptソースコード
       +-- インラインコメント（#で始まる行）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nodes.html | `docs/v1/annotated-source/nodes.html` | 生成HTML | 本画面のHTMLファイル |
| nodes.coffee | `src/nodes.coffee` | ソース | ASTノードクラス定義 |
| docco.css | `docs/v1/annotated-source/docco.css` | スタイル | ページスタイル定義 |
| scope.litcoffee | `src/scope.litcoffee` | ソース | 依存モジュール（スコープ管理） |
| helpers.coffee | `src/helpers.coffee` | ソース | 依存モジュール（ヘルパー関数） |
| lexer.coffee | `src/lexer.coffee` | ソース | 依存モジュール（字句解析器） |
| index.html | `docs/v1/annotated-source/index.html` | 生成HTML | Annotated Sourceインデックス |
