【ジェイエスドック】
JSDoc とは？
💡 コメントを書くだけでドキュメントが生まれる魔法のルール
📌 このページのポイント
- JavaScriptのコメントに @param や @returns などのタグを書いてドキュメントを生成する仕組み
- VSCodeなどのエディタが JSDoc コメントを読み取り、コード補完や型チェックに活用する
- TypeScriptを使わなくても、JSDocで型情報を記述すればある程度の型安全性が得られる
- JavaのJavadocに影響を受けた設計で、多くのプログラミング言語に似た仕組みがある
ひよこ JSDocって何のために使うの？
ペンギン先生 ひよこ どんなふうに書くの？
ペンギン先生 /** */というブロックコメントの中に、@param {string} name - ユーザー名 のようにタグを書くんだ。@param で引数の型と説明、@returns で戻り値、@throws で例外を記述できるよ
ひよこ TypeScriptがあればJSDocはいらないんじゃないの？
ペンギン先生 いい質問だね。実はTypeScriptを導入できないプロジェクトでもJSDocで型情報を書けば、VSCodeが型チェックしてくれるんだ。tsconfig.jsonで「checkJs」を有効にすると、JSDocの型アノテーションをTypeScriptの型チェッカーが読み取ってくれるよ
ひよこ 大きなプロジェクトでも使われているの？
ペンギン先生 実はGoogleの社内標準コーディングスタイルにもJSDocが含まれているよ。SvelteやPreactなど、あえてTypeScriptではなくJSDoc + JavaScriptで開発しているプロジェクトもあるんだ。ビルドステップが不要で、純粋なJavaScriptのまま型の恩恵を受けられるのが理由だね
ひよこ ドキュメント生成以外にも活用方法があるんだね！
ペンギン先生 そうなんだ。最近はTypeScriptの型定義ファイル（.d.ts）をJSDocから自動生成することもできるよ。ライブラリをJavaScriptで書きつつ、利用者にはTypeScriptの型情報を提供する、というハイブリッドなアプローチが注目されているんだ
まとめ：ざっくりこれだけ覚えればOK！
「JSDoc」って出てきたら「JavaScriptのコメントで型情報やドキュメントを書く仕組み」と思えればだいたいOK！
📖 おまけ：英語の意味
「JSDoc」 ＝ JavaScript Documentation
💬 「JavaScript」と「Documentation（ドキュメント）」を組み合わせた名前。JavaのJavadocにインスパイアされて作られたよ