# 画面設計書 16-Usage-API

## 概要

本ドキュメントは、Prettierドキュメントサイトの「Usage - API」画面の設計書です。この画面はPrettierのプログラマティックAPIの使用方法を詳細に説明するドキュメントページです。

### 本画面の処理概要

この画面はPrettierをJavaScriptコードから直接呼び出すためのAPI仕様を説明する静的ドキュメントページです。format、check、formatWithCursor、resolveConfig等の公開関数の使用方法と引数・戻り値を詳細に解説しています。

**業務上の目的・背景**：エディタ拡張、ビルドツール、カスタムスクリプトなど、PrettierをプログラムからI呼び出すユースケースは多数存在します。この画面は、開発者がPrettier APIを正しく活用してカスタム統合を構築できるよう、全公開APIの仕様を提供します。

**画面へのアクセス方法**：ユーザーはメインサイトのナビゲーションバーから「Docs」セクションに入り、サイドバーの「Usage」カテゴリ内の「API」リンクをクリックしてアクセスします。URLは `/docs/api` です。

**主要な操作・処理内容**：
1. `prettier.format(source, options)` - コードフォーマットの基本関数
2. `prettier.check(source, options)` - フォーマットチェック
3. `prettier.formatWithCursor(source, options)` - カーソル位置追跡フォーマット
4. `prettier.resolveConfig(filePath, options)` - 設定ファイル解決
5. `prettier.resolveConfigFile(filePath)` - 設定ファイルパス検索
6. `prettier.clearConfigCache()` - 設定キャッシュクリア
7. `prettier.getFileInfo(filePath, options)` - ファイル情報取得
8. `prettier.getSupportInfo()` - サポート情報取得

**画面遷移**：この画面からはオプションドキュメント、設定ファイルドキュメント、プラグインドキュメントへのリンクが設定されています。

**権限による表示制御**：なし。全ユーザーが同一のコンテンツを閲覧可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | コードフォーマット（format） | 主機能 | プログラマティックAPIでのformat関数の使い方を説明 |
| 2 | カーソル位置追跡フォーマット（formatWithCursor） | 補助機能 | APIでのformatWithCursor関数の使い方を説明 |
| 3 | フォーマットチェック（check） | 補助機能 | APIでのcheck関数の使い方を説明 |
| 13 | 設定ファイル解決（resolveConfig） | 補助機能 | APIでの設定解決関数の使い方を説明 |
| 14 | 設定ファイルパス検索（resolveConfigFile） | 補助機能 | APIでの設定ファイルパス検索の使い方を説明 |
| 16 | 設定キャッシュクリア（clearConfigCache） | 補助機能 | APIでの設定キャッシュクリアの使い方を説明 |
| 27 | ファイル情報取得（getFileInfo） | 補助機能 | APIでのgetFileInfo関数の使い方を説明 |
| 28 | サポート情報取得（getSupportInfo） | 補助機能 | APIでのgetSupportInfo関数の使い方を説明 |
| 29 | ASTパース（__debug.parse） | 補助機能 | APIでのデバッグパース関数の使い方を説明 |
| 30 | ASTからDoc生成（__debug.printToDoc） | 補助機能 | APIでのデバッグDoc生成関数の使い方を説明 |

## 画面種別

ドキュメント / 参照

## URL/ルーティング

- **URL**: `/docs/api`
- **ソースファイル**: `docs/api.md`
- **生成方式**: Docusaurus docs機能によるMarkdownからの静的HTML生成

## 入出力項目

本画面は静的ドキュメントページのため、ユーザー入力フィールドはありません。

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| prettier.format | format関数 | コードをフォーマットして文字列を返す |
| prettier.check | check関数 | フォーマット済みかをbooleanで返す |
| prettier.formatWithCursor | formatWithCursor関数 | カーソル位置を追跡しながらフォーマット |
| prettier.resolveConfig | resolveConfig関数 | ファイルパスから設定を解決 |
| prettier.resolveConfigFile | resolveConfigFile関数 | 設定ファイルのパスを検索 |
| prettier.clearConfigCache | clearConfigCache関数 | 設定キャッシュをクリア |
| prettier.getFileInfo | getFileInfo関数 | ファイルの無視状態とパーサーを取得 |
| prettier.getSupportInfo | getSupportInfo関数 | サポート言語・オプション情報を取得 |
| Custom Parser API (removed) | 削除されたAPI | v3.0.0で削除されたカスタムパーサーAPI |

## イベント仕様

### 1-内部リンククリック

- `options.md` → オプションドキュメント
- `configuration.md` → 設定ファイルドキュメント
- `plugins.md` → プラグインドキュメント

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

本画面は静的ドキュメントページのため、データベース更新は発生しません。

## メッセージ仕様

本画面は静的ドキュメントページのため、動的メッセージはありません。

## 例外処理

| 状態 | 説明 |
|------|------|
| ページ未発見（404） | URLが誤っている場合、Docusaurus標準の404ページを表示 |

## 備考

- 全APIは非同期（Promise返却）、同期版が必要な場合は`@prettier/sync`を使用
- Custom Parser APIはv3.0.0で削除、Plugin APIへの移行が必要
- resolveConfigのeditorconfig統合オプションで.editorconfigを考慮可能
- getSupportInfoの戻り値にはlanguages配列が含まれ、isSupported関数で動的判定可能

---

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

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

### 推奨読解順序

#### Step 1: ドキュメントコンテンツを理解する

本画面のコンテンツはMarkdownファイルで管理されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | api.md | `docs/api.md` | 公開API全体像を理解 |

**読解のコツ**: 各API関数はコード例付きで説明されています。

#### Step 2: 公開APIのエクスポートを理解する

Prettierが公開するAPIのエントリーポイントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/index.js` | format, check, resolveConfig等のエクスポート |

**主要処理フロー**:
1. 各公開関数のエクスポート定義
2. 内部モジュールからの関数インポート

#### Step 3: コアフォーマット処理を理解する

format/formatWithCursor関数の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.js | `src/main/core.js` | formatWithCursor関数の実装 |

**主要処理フロー**:
1. **324-367行目**: formatWithCursor関数の本体
2. **28-182行目**: coreFormat関数（内部処理）
3. **184-246行目**: formatRange関数（範囲フォーマット）

#### Step 4: 設定解決処理を理解する

resolveConfig関数の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | resolve-config.js | `src/config/resolve-config.js` | resolveConfig, resolveConfigFile関数 |

**主要処理フロー**:
1. **70-97行目**: resolveConfig関数の本体
2. **102-108行目**: resolveConfigFile関数
3. **110-129行目**: mergeOverrides関数（オーバーライド適用）

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

```
prettier.format(source, options)
    │
    └─ src/index.js (エクスポート)
           │
           └─ src/main/core.js: formatWithCursor()
                  │
                  ├─ normalizeFormatOptions()
                  │      └─ オプション正規化
                  │
                  ├─ parseText()
                  │      └─ ソースコードをASTにパース
                  │
                  ├─ printAstToDoc()
                  │      └─ ASTからDocを生成
                  │
                  └─ printDocToString()
                         └─ Docを文字列に変換
```

### データフロー図

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

ソースコード ─────────▶ prettier.format() ─────────▶ フォーマット済みコード
+ options                      │
                               ├─ parseText() → AST
                               ├─ printAstToDoc() → Doc
                               └─ printDocToString() → String

ファイルパス ─────────▶ resolveConfig() ─────────▶ オプションオブジェクト
                               │
                               ├─ loadPrettierConfig()
                               ├─ loadEditorconfig()
                               └─ mergeOverrides()

ファイルパス ─────────▶ getFileInfo() ─────────▶ { ignored, inferredParser }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.md | `docs/api.md` | ドキュメント | APIガイド |
| index.js | `src/index.js` | ソース | 公開APIエクスポート |
| core.js | `src/main/core.js` | ソース | コアフォーマット処理 |
| resolve-config.js | `src/config/resolve-config.js` | ソース | 設定解決処理 |
| parse.js | `src/main/parse.js` | ソース | パース処理 |
| ast-to-doc.js | `src/main/ast-to-doc.js` | ソース | AST→Doc変換 |
| support.js | `src/main/support.js` | ソース | サポート情報 |
| options.md | `docs/options.md` | ドキュメント | オプションドキュメント（関連参照） |
| configuration.md | `docs/configuration.md` | ドキュメント | 設定ファイルドキュメント（関連参照） |
