jsdoc

JSDoc

概要

JSDoc は JavaScript 用のドキュメント生成ツールです。コードのすぐ上にドキュメントコメントを記述すると、JSDoc がそのコメントを解析して API ドキュメントを生成します。

基本原則：公開 API を明確に文書化し、コメントをコードの近くに配置して、実装の変更に合わせてドキュメントが正確に保たれるようにします。

---

コメントのルール

• JSDoc ブロックは /** で始める必要があります（スラッシュの後にアスタリスクが 2 つだけ続きます）。
• /*、/***、またはそれ以上の数のアスタリスクで始まるブロックは、JSDoc パーサーによって無視されます。
• 文書化するシンボル（関数、クラス、メソッド、モジュールなど）の直前にコメントを配置します。
• まず公開 API と再利用可能な API を文書化します。

---

クイックスタート

/**
 * Adds two numbers.
 * @param {number} a - First number.
 * @param {number} b - Second number.
 * @returns {number} Sum of the two numbers.
 */
function add(a, b) {
  return a + b;
}

---

主なタグ

タグ	用途
@param {Type} name - description	関数のパラメーターを文書化します
@returns {Type} description	戻り値を文書化します
@constructor	関数をコンストラクターとして指定します
@todo text	ドキュメント内で保留中のタスクを管理します

プロジェクトに応じて、必要なタグ（@example、@throws、@deprecated、@see など）を追加で使用してください。

---

よくあるドキュメントのパターン

関数

/**
 * Formats a user's full name.
 * @param {string} firstName - User first name.
 * @param {string} lastName - User last name.
 * @returns {string} The formatted full name.
 */
function formatName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

コンストラクター形式の関数

/**
 * Represents a book.
 * @constructor
 * @param {string} title - Book title.
 * @param {string} author - Book author.
 */
function Book(title, author) {
  this.title = title;
  this.author = author;
}

TODO 注釈

/**
 * @todo Implement pagination support.
 * @todo Add validation for empty input.
 */
function listItems() {}

---

ドキュメントの生成

基本的な CLI の使い方：

jsdoc book.js

デフォルトでは、out/ ディレクトリに HTML ドキュメントが生成されます。

複数のソースファイルを渡すこともできます：

/path/to/jsdoc src/a.js src/b.js

CLI オプションやテンプレートのカスタマイズには、設定ファイルを指定できます。

---

ベストプラクティス

• 説明は簡潔かつ具体的にし、動作に焦点を当てます。
• パラメーターと戻り値の型を一貫して文書化します。
• 把握している未対応事項には @todo を含め、追跡できるようにします。
• API のシグネチャが変更されたら、コメントも更新します。
• まずエクスポートされたモジュールや公開モジュールを文書化し、必要に応じて内部ヘルパーも文書化します。
• 実行可能で現実的な例を保ちます。

---

よくある間違い

• JSDoc ブロックに /** ... */ ではなく /* ... */ を使用する。
• 説明対象のシンボルから離れた場所にコメントを書く。
• 関数の入力に対する @param の記載が不足している。
• API の動作ではなく実装の詳細を説明する。
• リファクタリング後にコメントが現在のコードと食い違う。

---

追加リソース

• reference.md — すぐに参照できる JSDoc 公式ドキュメントへのリンク。
• 公式ドキュメント：https://jsdoc.app