JSDoc でドキュメント注釈 — /** @param {number} x */ function f(x){}
JavaScript では JSDoc という「コメントで書くドキュメント注釈」を使うと、関数や変数の型情報や説明をコードに埋め込めるようになります。
初心者は「コメントで関数の使い方を説明する仕組み」と覚えると理解しやすいです。
VSCode などのエディタでは、JSDoc を書くと 入力補完や型チェックが効くようになるので便利です。
基本のコード例
/**
* 引数 x を2倍にして返す関数
* @param {number} x - 倍にしたい数値
* @returns {number} - 計算結果
*/
function double(x) {
return x * 2;
}
console.log(double(5)); // → 10
@param {型} 引数名→ 引数の型と説明を書く@returns {型}→ 戻り値の型を書く- コメントは
/** ... */の形式で書く
よく使うテンプレート集
複数引数の関数
/**
* 2つの数値を足し算する
* @param {number} a - 1つ目の数値
* @param {number} b - 2つ目の数値
* @returns {number} - 合計値
*/
function add(a, b) {
return a + b;
}
オブジェクトを引数に取る
/**
* ユーザー情報を表示する
* @param {{id: number, name: string}} user - ユーザーオブジェクト
*/
function printUser(user) {
console.log(`ID=${user.id}, Name=${user.name}`);
}
非同期関数
/**
* データを取得する
* @returns {Promise<string>} - 取得した文字列
*/
async function fetchData() {
return "data";
}
例題: 配列を処理する関数
/**
* 配列の平均値を計算する
* @param {number[]} arr - 数値の配列
* @returns {number} - 平均値
*/
function average(arr) {
const sum = arr.reduce((a, b) => a + b, 0);
return sum / arr.length;
}
console.log(average([10, 20, 30])); // → 20
- 効果: 配列の型（
number[]）を明示できる。
実務でのコツ
- VSCode で補完が効く: JSDoc を書くと関数呼び出し時に説明が表示される。
- 型チェックに役立つ: TypeScript を使わなくても簡易的な型チェックができる。
- チーム開発で必須: 関数の使い方をコメントで明示できるので、他の人が理解しやすい。
ありがちなハマりポイントと対策
- 書き忘れると補完が効かない: → 重要な関数には必ず JSDoc を書く。
- 型の書き方に注意:
string[]（文字列配列）、Promise<number>（数値を返す非同期処理）など正しい形式を使う。
練習問題（関数に JSDoc を付ける）
/**
* 名前を挨拶文に変換する
* @param {string} name - ユーザー名
* @returns {string} - 挨拶文
*/
function greet(name) {
return `こんにちは、${name}さん！`;
}
console.log(greet("Aki")); // → "こんにちは、Akiさん！"
直感的な指針
- JSDoc = コメントで型や説明を書く仕組み。
@paramで引数、@returnsで戻り値を説明。- エディタ補完や型チェックに役立つ。
- 初心者は「引数1つの関数」から練習すると理解が深まる。
これを覚えれば「関数の使い方をコード内で説明」できるようになり、読みやすく安全なコードが書けるようになります。