【ジェイエスドック】

JSDoc とは?

最終更新:
💡 コードのそばに書く、説明と型のメモ
📌 このページのポイント
JSDoc:説明と型情報をコードのそばへ 関数のそばのコメント/*** @param {string} name*/function greet(name) {}greet(name)name: stringJSDocツール対応エディタAPIのHTML文書補完・説明表示設定して型検査コメント自体は、動作を変えない.d.ts出力も文書生成とは別処理
青はJSDocツールのAPI文書生成、緑は対応エディタの補完・説明表示です。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ツールによる文書生成と、コメントの型情報を他のツールが使うことを分けて考えよう

参考資料

← 用語集にもどる