# 画面設計書 21-Annotated Source - Register

## 概要

本ドキュメントは、CoffeeScript v1のNode.js登録処理(register.coffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

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

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解したい開発者向けに、Node.js環境でCoffeeScriptファイルをrequireで直接読み込むための登録処理の仕組みを解説する。register.coffeeは`require.extensions`を拡張し、.coffeeや.litcoffee拡張子のファイルをNode.jsモジュールとして透過的に利用可能にする重要なモジュールである。

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

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. セクションアンカーリンクによる特定セクションへの直接アクセス
4. 関連モジュール(coffee-script.coffee, helpers.coffeeなど)への遷移

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 46 | require フック | 主機能 | Node.js登録処理register.coffeeのソースコード解説表示 |
| 50 | child_process.fork対応 | 補助機能 | forkパッチの解説を含む |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

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

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

| セクション番号 | 内容 | 対応コード行 |
|----------------|------|-------------|
| 1 | モジュールインポート | 1-4行目 |
| 2 | loadFile関数の定義 | 5-7行目 |
| 3 | require.extensions登録 | 8-10行目 |
| 4 | Module.loadパッチ | 11-16行目 |
| 5 | findExtension関数（ドットファイル対応） | 17行目 |
| 6 | findExtension関数（拡張子探索） | 18-24行目 |
| 7 | child_process.forkパッチ | 25-34行目 |

## イベント仕様

### 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系のソースコードを対象としている
- シンタックスハイライトはhighlight.jsを使用
- レスポンシブデザインに対応（viewport設定あり）

---

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

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

### 推奨読解順序

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

register.coffeeが操作する主要なデータ構造は、Node.jsの`require.extensions`オブジェクトと`Module`クラスである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | register.coffee | `src/register.coffee` | Module、require.extensionsの役割を理解 |

**読解のコツ**: Node.jsのモジュールシステムの仕組み（require、Module._extensions）を事前に理解しておくと読みやすい。

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

register.coffeeはCoffeeScript.register()呼び出し時、またはrequire('coffeescript/register')時に実行される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | register.coffee | `src/register.coffee` | 1-4行目でモジュールインポート |
| 2-2 | register.coffee | `src/register.coffee` | 32-34行目でrequire.extensions登録 |

**主要処理フロー**:
1. **1-4行目**: CoffeeScript、child_process、helpers、pathモジュールのインポート
2. **6-16行目**: スタックトレースパッチの適用判定
3. **19-28行目**: loadFile関数の定義（.coffeeファイル読み込み処理）
4. **32-34行目**: require.extensionsへの拡張子登録
5. **59-69行目**: child_process.forkのパッチ適用

#### Step 3: loadFile関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | register.coffee | `src/register.coffee` | 19-28行目：loadFile関数 |

**主要処理フロー**:
- **19行目**: loadFile関数の定義開始
- **20行目**: オプションの取得（親モジュールから継承）
- **24-25行目**: ソースマップのインライン化設定
- **26行目**: CoffeeScript._compileFileによるコンパイル
- **28行目**: module._compileで結果をNode.jsモジュールとして実行

#### Step 4: Module.loadパッチを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | register.coffee | `src/register.coffee` | 38-55行目：Module.loadパッチ |

**主要処理フロー**:
- **40-48行目**: findExtension関数（複数ドット拡張子対応）
- **50-55行目**: Module.prototype.loadのオーバーライド

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

```
require('coffeescript/register')
    |
    +-- CoffeeScript (from './')
    |       |
    |       +-- patchStackTrace()
    |
    +-- require.extensions[ext] = loadFile
    |       |
    |       +-- loadFile(module, filename)
    |               |
    |               +-- CoffeeScript._compileFile()
    |               +-- module._compile()
    |
    +-- Module::load = (filename) ->
    |       |
    |       +-- findExtension(filename)
    |       +-- Module._extensions[extension]()
    |
    +-- child_process.fork = (path, args, options) ->
            |
            +-- helpers.isCoffee(path)
            +-- fork(path, args, options)
```

### データフロー図

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

.coffee/.litcoffee -----> loadFile()                -----> JavaScriptコード
ファイル                        |
                               v
                    CoffeeScript._compileFile()
                               |
                               v
                    module._compile() -----------> 実行可能モジュール


child_process.fork() --> helpers.isCoffee() -----> 適切なバイナリで
(CoffeeScriptファイル)       |                      子プロセス起動
                            v
                    coffee バイナリパス設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| register.coffee | `src/register.coffee` | ソース | Node.js登録処理の実装 |
| register.html | `docs/v1/annotated-source/register.html` | テンプレート | Docco生成HTML |
| coffee-script.coffee | `src/coffee-script.coffee` | ソース | メインコンパイラ（v1） |
| helpers.coffee | `src/helpers.coffee` | ソース | ヘルパー関数（isCoffeeなど） |
| docco.css | `docs/v1/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
| index.coffee | `src/index.coffee` | ソース | Node.js APIエントリーポイント |
