【JavaScript入門】ドキュメントを作る

【JavaScript入門】ドキュメントを作る

　コードが増え、人が増えるほど “ドキュメント” はプロジェクトの生命線になります。メンバーごとに頭の中で把握している仕様や API を 静的ファイルとして残す ことで、オンボーディング時間を短縮し、バグ調査も迅速に行えます。JavaScript では JSDoc コメントを書くだけで自動的に HTML マニュアルを生成できるため、手作業で Wiki を更新するよりはるかに低コストです。以下では「ドキュメント化の種類」と「JSDoc ワークフロー」を整理し、最小構成の npm プロジェクト例を示します。

ポイント：JSDoc は コメント と 自動生成 の合わせ技。“実装と説明が同じファイルにある” ので 追従漏れ が起こりにくい。

1 分クイックスタート（npm + JSDoc）

まず、プロジェクト用のフォルダに移動します。

cd C:\Users\ユーザー名\Desktop\node-js

以下のコマンド操作を行います。

# 1. 新規プロジェクトフォルダ
mkdir jsdoc-demo 
cd jsdoc-demo
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

# 2. npm 初期化
npm init -y

# 3. JSDoc を dev 依存で追加
npm i -D jsdoc

# 4. ソース用ディレクトリ
mkdir src

ファイル名： src/Point.js（JSDoc コメント付き）

「src」フォルダに「Point.js」を作成します。

/** 点 (x, y) を表すクラス */
export default class Point {
  /** @param {number} x - X 座標 @param {number} y - Y 座標 */
  constructor(x, y) { this.x = x; this.y = y; }

  /** X を返す @returns {number} */
  getX() { return this.x; }

  /** Y を返す @returns {number} */
  getY() { return this.y; }

  /** 文字列 "x,y" → Point へ変換 @param {string} csv @returns {Point} */
  static fromCSV(csv) {
    const [x, y] = csv.split(',').map(Number);
    return new Point(x, y);
  }
}

生成コマンド

npx jsdoc src -d docs

• -d docs で docs/ に HTML が出力
• docs/index.html をブラウザで開けば API リファレンスが閲覧可能

まとめ

• ドキュメント = 成熟したコードの不可欠な一部。
• JSDoc は「コメントを書く → コマンド一発で API サイト生成」という 低コスト・高リターン の手段。
• 生成物を GitHub Pages / VitePress / Docusaurus でホスティングすれば “いつでも最新仕様” をチーム全員が参照できる。
  まずは小さなユーティリティ関数から JSDoc コメントを付け、CI で自動生成→デプロイするパイプラインを組んでみましょう。