JSDoc 3入門

入門

JSDoc 3は、JavadocやphpDocumentorに類似した、JavaScript用のAPIドキュメント生成ツールです。ドキュメントのコメントをソースコードに直接追加します。コード自体のすぐ隣に配置します。JSDocツールはソースコードをスキャンし、HTML形式のドキュメントWebサイトを生成します。

コードにドキュメントのコメントを追加する

JSDocの目的は、JavaScriptアプリケーションまたはライブラリのAPIについてドキュメントを作成することです。モジュール、名前空間、クラス、メソッド、メソッドのパラメータなどのドキュメントを作成する必要があります。

通常、JSDocのコメントは、ドキュメントを作成するコードの直前に配置する必要があります。各コメントは、JSDocパーサーが認識するために、/**シーケンスで始める必要があります。/*、/***、3つ以上の星で始まるコメントは無視されます。これは、コメントブロックの解析を抑制するための機能です。

/** This is a description of the foo function. */
function foo() {
}

説明を追加するのは簡単です。ドキュメントのコメントに必要な説明を入力するだけです。

特殊な「JSDocタグ」を使用して、詳細な情報を提供できます。たとえば、関数がクラスのコンストラクタである場合は、@constructorタグを追加することで示すことができます。

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

より多くのタグを使用して、さらに情報を追加できます。JSDoc 3が認識するタグの完全なリストは、ホームページを参照してください。

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

Webサイトの生成

コードにコメントが追加されたら、JSDoc 3ツールを使用してソースファイルからHTML形式のWebサイトを生成できます。

デフォルトでは、JSDocは組み込みの「デフォルト」テンプレートを使用して、ドキュメントをHTMLに変換します。必要に応じて、このテンプレートを編集するか、まったく新しいテンプレートを作成できます。

jsdoc book.js

このコマンドを実行すると、現在の作業ディレクトリにアウト/という名前のディレクトリが作成されます。そのディレクトリ内に、生成されたHTMLページがあります。