---
name: jsdoc
description: TypeScript の JSDoc を書くときに使用します。タグの使い方と記述順を定めます。
---

# JSDoc

あらゆるケースを網羅した詳しい JSDoc フォーマットガイドです。常に適用する基本ルールは `jsdoc` ルールにまとめています。このガイドは、詳しい仕様を確認したいときのリファレンスとして使ってください。

## タグ

### よく使うタグ

| タグ | 用途 | 補足 |
| --- | --- | --- |
| `@default` | デフォルト値 | デフォルト値が自明でない場合のみ使用します（`undefined` は不要）。 |
| `@note` | 注意事項 | バージョン情報や破壊的変更などを記載します。 |
| `@deprecated` | 非推奨であることを示す | 移行方法もあわせて記載します。 |

### 必要な場合のみ使うタグ

| タグ | 用途 |
| --- | --- |
| `@see` | 外部ドキュメントへの参照 |
| `@internal` | 内部 API |
| `@beta` | 実験的な機能 |

### 使用しないタグ（TypeScript がすでに提供しているため）

- `@type`：TypeScript の型注釈を利用します
- `@typedef`：`type` または `interface` を利用します
- `@example`：使用しません
- `@default undefined`：オプショナル (`?`) であることがすでに `undefined` を意味します

### 使用に留意点のあるタグ

| タグ | 留意点 | 正しい例 | 誤った例 |
| --- | --- | --- | --- |
| `@param` | 型表記とダッシュが不要 | `@param 説明`   | `@param {ArrayBuffer} value - 説明` |
| `@returns` | 型表記とダッシュが不要 | `@returns 説明` | `@returns {string} - 説明` |

## ドキュメントの書き方

### シンプルなプロパティー

常に複数行の JSDoc を使用します。

```ts
/**
 * 生成されるファイルの出力先ディレクトリーです。
 */
outDir?: string
```

`/** 説明 */` のような 1 行形式は使用せず、必ず複数行で記述してください。

### 自明でないデフォルト値を持つプロパティー

```ts
/**
 * トラバーサル中に同時実行されるコールバックの最大数です。
 *
 * 値を大きくすると I/O バウンドな処理をより並列化でき、小さくするとメモリ使用量を抑えられます。
 *
 * @default 30
 */
concurrency?: number
```

TypeScript の型だけでデフォルト値が明らかな場合（`false` や `undefined` など）は、`@default` を付けないでください。

### 列挙値・ユニオン型

```ts
/**
 * 関数シグネチャでパスパラメータをどのように出力するかを指定します。
 *
 * - `"object"`: 分割代入された単一のオブジェクト引数としてまとめます。
 * - `"inline"`: 各パラメータを個別の引数として展開します。
 * - `"inlineSpread"`: 単一の可変長引数として出力します。
 */
pathParamsType: "object" | "inline" | "inlineSpread";
```

### ネストされたプロパティー

各プロパティごとに、それぞれ独立した複数行 JSDoc を記述します。

```ts
names?: {
  /**
   * リクエストボディ引数の名前です。
   *
   * @default "data"
   */
  data?: string

  /**
   * クエリパラメータをまとめる引数の名前です。
   *
   * @default "params"
   */
  params?: string
}
```

### 関数のドキュメント

シグネチャーだけでは伝わらない情報がある場合にのみ JSDoc を追加します。

```ts
// シグネチャだけで十分に意味が分かるため、JSDoc は不要です。
function camelCase(str: string): string { ... }

// 振る舞いや分かりにくい仕様を説明できるため、JSDoc を付けます。
/**
 * スキーマが通常の文字列として扱われる場合に `true` を返します。
 *
 * - `string`、`uuid`、`email`、`url`、`datetime` は常に通常の文字列です。
 * - `date` と `time` は、`representation` が `'string'` の場合のみ通常の文字列になります。
 */
function isStringType(node: SchemaNode): boolean { ... }
```

### 改行ルール

1文の途中で改行しないでください。

正しい例:

```ts
/**
 * これは本来とても長い文章ですが、途中で改行しません。
 *
 * @param value これは本来とても長い文章ですが、途中で改行しません。
 */
```

誤った例:

```ts
/**
 * これはとても長い文章なので、
 * 句読点などで途中で改行してしまいます。
 *
 * @param value これはとても長い文章なので、
 *              句読点などで途中で改行してしまいます。
 */
```

## 実装コードのドキュメント

必要に応じて、読み手がコードの背景や意図、ロジックをすぐ理解できるよう、簡潔で丁寧な技術解説を添えます。その場合はインラインコメント `// ` で書きます。

## ガイドライン

### 推奨

- TypeScript の型ではなく、そのプロパティーや関数の役割を説明します。
- 公開する型・プロパティ・関数には必ず JSDoc を付けます。
- JSDoc は常に複数行で記述します。
- 具体的で完結した文章を書きます。
- `@default` はデフォルト値が自明でない場合のみ付けます。
- JSDoc には、振る舞いを記述します。
- 実装コードには、必要に応じて、読み手がコードの背景、意図、ロジックを即座に理解できるようなコメントを記述します。

### 非推奨

- JSDoc で `/** 説明 */` のような 1 行形式を使わないでください。
- `@default undefined` を書かないでください。
- `@example` を書かないでください。
- 自明なプロパティーまで過剰に説明しないでください。

## タグの記述順

1. 説明（必須）
2. 主な外観や動作の箇条書き（必要な場合）
3. `@param`（必要な場合）
4. `@default`（デフォルト値が自明でない場合）
5. `@returns`（必要な場合）
6. `@note`（必要な場合）
7. `@deprecated`（非推奨の場合）
8. `@see`（関連資料を示す場合）