JSDocとは？JavaScriptのコメントから自動でドキュメント生成する方法

JavaScriptでコードを書いていて、「この関数、何のパラメータを受け取るんだっけ？」「戻り値の型は何だったかな？」と迷ったことはありませんか？JSDocを使えば、コメントからドキュメントを自動生成でき、チーム開発での情報共有が格段に楽になります。

この記事では、JSDocの基本的な使い方から実践的な書き方まで、サクッと理解できる内容をお届けします。

JSDocとは？

JSDocは、JavaScriptのコメントから自動的にドキュメントを生成するツールです。特定の形式でコメントを書くだけで、HTMLドキュメントが自動生成されます。

JSDocのメリット

• 型情報の明示：TypeScriptを使わなくても型情報を記述できる
• エディタ補完：VSCodeなどのエディタで関数の説明や型が表示される
• ドキュメント自動生成：HTMLドキュメントが自動で作成される
• チーム開発の効率化：関数の仕様が一目で分かる
• 学習コストが低い：コメントに特定のタグを追加するだけ

基本的な書き方

JSDocのコメントは、/**で始まり*/で終わります。通常のコメント/*ではなく、アスタリスクが2つであることがポイントです。

関数の基本的な例

/**
 * 2つの数値を足し算する関数
 * @param {number} a - 1つ目の数値
 * @param {number} b - 2つ目の数値
 * @returns {number} 足し算の結果
 */
function add(a, b) {
  return a + b;
}

この例では、以下の情報が記述されています：

• 関数の説明（1行目）
• パラメータの型と説明（@param）
• 戻り値の型と説明（@returns）

VSCodeでの表示

VSCodeでこの関数にカーソルを合わせると、JSDocの内容がツールチップで表示されます。パラメータの型や説明が一目で分かるため、開発効率が大幅に向上します。

よく使うJSDocタグ

JSDocには様々なタグがありますが、実務でよく使うものを紹介します。

@param – パラメータの型と説明

/**
 * @param {string} name - ユーザー名
 * @param {number} age - 年齢
 * @param {boolean} [isActive=true] - アクティブフラグ（オプション）
 */
function createUser(name, age, isActive = true) {
  // ...
}

オプションパラメータは[]で囲み、デフォルト値は=で記述します。

@returns – 戻り値の型と説明

/**
 * @returns {string} ユーザーのフルネーム
 */
function getFullName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

@type – 変数の型定義

/** @type {string} */
const userName = 'John';

/** @type {number[]} */
const scores = [95, 87, 92];

@typedef – カスタム型の定義

/**
 * @typedef {Object} User
 * @property {number} id - ユーザーID
 * @property {string} name - ユーザー名
 * @property {string} email - メールアドレス
 */

/**
 * @param {User} user - ユーザーオブジェクト
 */
function displayUser(user) {
  console.log(user.name);
}

@example – 使用例の記載

/**
 * 配列の合計を計算する
 * @param {number[]} numbers - 数値の配列
 * @returns {number} 合計値
 * @example
 * const total = sum([1, 2, 3, 4]);
 * console.log(total); // 10
 */
function sum(numbers) {
  return numbers.reduce((acc, num) => acc + num, 0);
}

実践例：複雑なオブジェクトの型定義

実務でよくある、複雑なオブジェクトを扱う場合の記述例です。

/**
 * @typedef {Object} Product
 * @property {number} id - 商品ID
 * @property {string} name - 商品名
 * @property {number} price - 価格
 * @property {string[]} tags - タグ配列
 */

/**
 * @typedef {Object} CartItem
 * @property {Product} product - 商品情報
 * @property {number} quantity - 数量
 */

/**
 * カート内の商品の合計金額を計算
 * @param {CartItem[]} cartItems - カート内商品の配列
 * @returns {number} 合計金額
 */
function calculateTotal(cartItems) {
  return cartItems.reduce((total, item) => {
    return total + (item.product.price * item.quantity);
  }, 0);
}

HTMLドキュメントの生成方法

JSDocを使ってHTMLドキュメントを生成する手順です。

Step 1: JSDocのインストール

npm install --save-dev jsdoc

Step 2: ドキュメント生成コマンドの実行

# 単一ファイルの場合
npx jsdoc src/index.js

# ディレクトリ全体の場合
npx jsdoc -r src/

Step 3: 生成されたドキュメントの確認

デフォルトではout/ディレクトリにHTMLが生成されます。out/index.htmlをブラウザで開くと、美しいドキュメントが確認できます。

package.jsonにスクリプトを追加

{
  "scripts": {
    "docs": "jsdoc -r src/ -d docs"
  }
}

これでnpm run docsで簡単にドキュメント生成できます。

TypeScriptとの使い分け

「JSDocとTypeScript、どっちを使えばいいの？」という疑問について。

JSDocがおすすめの場合：

• 既存のJavaScriptプロジェクトに型情報を追加したい
• TypeScriptのコンパイル手順を追加したくない
• 学習コストを抑えたい
• ドキュメント生成が主な目的

TypeScriptがおすすめの場合：

• 新規プロジェクトで最初から型安全性を重視したい
• より厳密な型チェックが必要
• 大規模プロジェクトでの開発
• 最新のJavaScript機能を使いたい

まとめ：JSDocで開発効率を上げよう

JSDocは、コメントを書くだけで型情報とドキュメントを同時に提供できる便利なツールです。TypeScriptほど本格的ではありませんが、手軽に導入できて効果が高いのが魅力です。

JSDoc活用のポイント：

• /**で始まるコメントを使う
• @paramでパラメータの型と説明を記述
• @returnsで戻り値を明示
• @typedefでカスタム型を定義
• VSCodeなどのエディタで補完が効く
• HTMLドキュメントを自動生成できる

まずは簡単な関数から始めて、徐々にプロジェクト全体に適用していきましょう。チーム開発での情報共有が格段に楽になり、バグの削減にもつながります。

JavaScript開発をさらに効率化する関連記事

JSDocでドキュメント管理を効率化したら、他の開発ツールやAI支援ツールも活用して、さらに生産性を向上させましょう：

開発効率化・コーディング支援

• opencode – ターミナル向けAIコーディングエージェント！複数モデル対応で柔軟な開発支援を実現 – ターミナルから直接AIを活用してコーディング効率を大幅向上
• Qoder – AIが完全理解するソフトウェア開発向け次世代IDE – プロジェクト全体を理解するAI搭載IDEで開発体験を革新
• Byterover – AI開発者向け自己改善型コーディング知識管理プラットフォーム – コーディングパターンを蓄積してチーム全体の開発品質を向上

コード品質向上

• Cipher by Byterover – AIコーディング支援のための共有メモリー管理プラットフォーム – コーディング履歴を自動記録してプロジェクト間で知識共有
• Qwen3-Coder – AIによる大規模コード生成を実現する次世代オープンソースモデル – 高精度なコード生成でボイラープレート作成を自動化

JSDoc よくある質問

❓ JSDocとTypeScriptはどちらを使うべきですか？

既存のJavaScriptプロジェクトに型情報を追加したい場合や、学習コストを抑えたい場合はJSDocがおすすめです。新規プロジェクトで最初から厳密な型チェックを行いたい場合や、大規模開発ではTypeScriptが適しています。JSDocは導入が簡単でコンパイル不要なため、小〜中規模プロジェクトでは十分な選択肢になります。

❓ JSDocを書いてもエディタで補完が効きません

VSCodeの場合、JavaScriptの型チェック機能を有効にする必要があります。ファイルの先頭に// @ts-checkを追加するか、jsconfig.jsonまたはtsconfig.jsonで"checkJs": trueを設定してください。これにより、JSDocの型情報を使ったエディタ補完とエラーチェックが有効になります。

❓ JSDocのドキュメント生成は必須ですか？

いいえ、必須ではありません。JSDocの最大のメリットは、エディタでの型補完や型チェックです。HTMLドキュメント生成は便利な機能ですが、必ずしも使う必要はありません。まずはコメントとしてJSDocを書き始めて、エディタの補完機能を活用することから始めるのがおすすめです。ドキュメント生成は必要に応じて後から導入できます。

❓ JSDocで配列やオブジェクトの型はどう書きますか？

配列は{型名[]}の形式で記述します（例：{string[]}、{number[]}）。オブジェクトは@typedefを使ってカスタム型を定義するか、インラインで{Object}と記述し、@propertyでプロパティを列挙します。ネストしたオブジェクトや複雑な構造も、@typedefを組み合わせることで表現できます。