【ジェイエスドック】
JSDoc とは？
最終更新:
💡 コードのそばに書く、説明と型のメモ
JavaScriptのソースコードに特別なコメントを書くことで、APIドキュメントを自動生成できるツール・記法。型情報の補完にも使われる。
📌 このページのポイント
- JSDocでは/** */コメントに@paramや@returnsなどを書いてAPIを説明する
- JSDocツールを実行すると、コメントからHTML文書などを生成できる
- 対応エディタは型情報を補完に利用し、設定に応じて型検査する
- 文書生成とTypeScriptによる型検査・型宣言の出力は別の処理
ひよこ JSDocって何のために使うの？
ペンギン先生 JavaScriptの関数やクラスに説明や型情報を添えるために使うよ。JSDocツールはコメントを読み、HTMLのAPI文書などを生成する。VS Codeのような対応エディタも、コメントをコード補完や説明表示に使えるんだ。
ひよこ どんなふうに書くの？
ペンギン先生 JSDocでは/** */というブロックコメントに、たとえば@param {string} name - ユーザー名と書くよ。@paramは引数、@returnsは戻り値、@throwsは投げる可能性があるエラーを説明する。コメントを書くだけで関数の実際の動作が変わるわけではないんだ。
ひよこ JavaScriptのまま型チェックできるの？
ペンギン先生 VS CodeではTypeScriptの型検査機能を使えるよ。ファイル先頭に// @ts-checkを置くか、jsconfig.jsonでcheckJsを有効にする。tsconfig.jsonを使うならallowJsも設定するんだ。JSDocの型情報だけを書いて、型検査が必ず有効になるわけではないよ。
ひよこ TypeScriptがあればJSDocはいらないんじゃないの？
ペンギン先生 型はTypeScriptの構文で書けるけど、引数の意味や使い方の説明は別に必要だね。JavaScriptに型情報を添えたい場合にもJSDocが役立つ。どのタグを使えるかは、文書生成ツールやエディタ・型検査側の対応を確認しよう。
ひよこ 型定義ファイルも作れるって聞いたよ？
ペンギン先生 TypeScriptコンパイラは、JavaScriptとJSDocの型情報から.d.tsファイルを出力できるよ。allowJsとdeclarationなどの設定が必要で、型宣言だけならemitDeclarationOnlyを使う。JSDocのHTML文書生成とは別の処理で、利用者へ型情報を渡すためのものなんだ。
まとめ：ざっくりこれだけ覚えればOK！
「JSDoc」って出てきたら「JavaScriptのコメントで型情報やドキュメントを書く仕組み」と思えればだいたいOK！
📖 おまけ：英語の意味
「JSDoc」 ＝ JavaScript Documentation
💬 JavaScriptの文書を表す名前だよ。JSDocツールによる文書生成と、コメントの型情報を他のツールが使うことを分けて考えよう