TL;DR

JavaScript の API ドキュメントを生成するツールである。Javadoc や phpDocumentor に似ている。/** で始まるコメントに @param などのタグを書き、そこから HTML のドキュメントを作る。

なぜ必要か

コメントからドキュメントを生成できる。また、TypeScript は JavaScript ファイルの JSDoc を型情報として読むので、checkJs や // @ts-check を有効にすれば、JavaScript のまま型チェックを受けられる。

仕組み

JSDoc のコメントは、ドキュメントにするコードの直前に置く。JSDoc のパーサに認識されるには、コメントが /** で始まっている必要がある。コメントを書いたら、jsdoc book.js のようにコマンドを実行すると、カレントディレクトリに out/ ディレクトリが作られ、HTML のドキュメントが出力される。

TypeScript は、@type、@param、@returns、@typedef、@template などのタグを型情報として扱う。ここに挙がっていないタグ(@async など)はまだ対応していない。TypeScript のファイルでは、@deprecated や @see などのドキュメント用のタグだけが使える。

例

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {}

注意点

Effective TypeScript 第2版 ―型システムの力を最大限に引き出す83項目 によると、JavaScript ファイルの先頭に // @ts-check を書けば型チェックを試せるが、チェックはかなり緩い。最終的なゴールは TypeScript への置き換えなので、JSDoc で完璧に型を付けることに時間をかけない。また、TypeScript に移行すると JSDoc の型が強制されなくなるので、型安全性を失うことがある。

TSDoc のページによると、JSDoc は文法が厳密に定められておらず、JSDoc をもとにしたツールはそれぞれ独自に拡張している。TSDoc は、TypeScript のドキュメントコメントの書き方を標準化するための提案である。

関連

出典