JSDoc形式 - Lampass

JSDoc形式とは、JavaScriptやTypeScriptでコードに
ドキュメンテーション（文書化）コメントを記述するための
標準的な記法ルールのことです。

主に次の目的で使われます：

関数やコンポーネントの使い方を説明する
引数や戻り値の型を明示する
エディタの補完やツール（例：VSCode, TypeScript, Storybook）に情報を渡す
自動ドキュメント生成ツール（例：JSDoc, TypeDoc）と連携する

🔧 JSDocの基本構文

js

/**
 * この関数は2つの数値を加算します。
 *
 * @param {number} a - 最初の数値
 * @param {number} b - 2番目の数値
 * @returns {number} 加算された結果
 */
function add(a, b) {
  return a + b;
}

🏷️ よく使うJSDocタグ一覧

タグ	用途	例
`@param`	引数の説明	`@param {string} name - ユーザー名`
`@returns`	戻り値の型と説明	`@returns {boolean} 成功したかどうか`
`@example`	使用例を記載	`@example const result = add(1, 2);`
`@typedef`	型の定義	`@typedef {Object} User`
`@component`	Reactコンポーネントの目印	`@component`
`@deprecated`	非推奨であることを示す	`@deprecated 代わりに useNewFunc()`
`@default`	デフォルト値の説明	`@default true`

🧠 JSDocを使うメリット

チーム開発でコードの理解が早くなる
自動ドキュメントを生成できる
VSCodeなどで補完やツールチップが表示される
型がないJavaScriptでも補助的に型チェックが可能

TypeScriptを使っている場合は？

TypeScriptでは型定義が既にコードにあるため、JSDocは補助的な役割になりますが、

コメントとしての説明
@exampleや@deprecatedなどの補足

は依然としてとても有用です。

VSCodeの拡張機能で、自動生成も可能です。

Visual Studio Code（VSCode）でJSDocコメントを効率的に書くための拡張機能
のおすすめリストです：

🧩 おすすめ JSDoc 用 VSCode 拡張機能

1. ✅ Document This

概要：関数や変数の上でショートカットキーを押すだけで、
JSDocコメントを自動生成してくれます。
機能：
- 関数・クラス・変数に対するJSDocのテンプレート生成
- TypeScript対応（型を自動で取り込む）
使い方：
- 関数の上で Ctrl + Alt + D（Macは Cmd + Option + D）を２回でコメントを挿入
インストールURL：Document This – VSCode Marketplace

2. ✍️ JSDoc Comments

概要：JSDocテンプレートを手動または自動で入力補完してくれる拡張
機能：
- /** と入力すると、自動的にテンプレートが挿入される
- スニペット形式でタグ補完が可能
使い方：
- /** を入力して Enter でテンプレート挿入
インストールURL：JSDoc Comments – VSCode Marketplace

3. 🧠 TypeScript Hero

概要：JSDoc以外にも、TypeScriptでの型補完、インポートの自動管理、
　　　ナビゲーションなどに強力
特徴：
- JSDoc支援というよりはTypeScript全体をサポート
インストールURL：TypeScript Hero – VSCode Marketplace

💡補足：他の便利なツール

ツール名	機能概要
ESLint + eslint-plugin-jsdoc	JSDocの書き方をルール化してチェックできます（例：全関数にJSDoc必須など）
TypeDoc	TypeScriptからHTML形式のドキュメント生成が可能なCLIツール。VSCode拡張ではないが便利です。

📝 まとめ

拡張機能	主な用途
Document This	JSDocコメントの自動生成
JSDoc Comments	テンプレート補完・タグ入力
TypeScript Hero	型支援・開発全般支援

どれを使うべきかは、
”自動化したいか（Document This）or 手動でも補完が欲しいか（JSDoc Comments）”
で選ぶと良いです。