• atwiki
  • JsDoc Toolkitを使う!

JsDoc Toolkitを使う!

最終更新:

aias-jsdoctoolkit

- view
管理者のみ編集可

このサイトについて

「JsDoc Toolkitを使う!」は、JavaScriptドキュメンテーションツールであるJsDoc Toolkitの使い方を紹介するサイトです。JsDoc Toolkitは非常に優れたツールですが、まとまった日本語の情報が少ないようなので何となく作ってみました。
  • このサイトの内容はあくまで管理人個人の理解に基づくものです。ご利用は自己責任でお願いします。
  • 記載されている情報はバージョン 2.4.0 時点のものです。

JsDoc Toolkitとは

JsDoc Toolkit は、JavaScriptソースコードに記述されたコメントを元に、HTML形式のドキュメントを生成するオープンソースのフリーソフトウェアです。作者はMichael Mathews、ライセンスはMITライセンスです。
  • JavaScriptのドキュメント作成ツールとしては JSDoc が良く知られていますが、JsDoc ToolkitとJSDocは全く別のものです。(ちなみにMichael MathewsはJSDocの主要な開発者の一人だったようです)なおJSDocは既に開発を停止しており、JsDoc Toolkitはその後継プロジェクトとされています。

JsDoc Tooikitはそれ自身がJavaScriptで記述されており、JavaによるJavaScriptの実装である Rhino 上で動作します。従ってJsDoc Tooikitを使用するにはJavaの実行環境(JRE)が必要です。
  • JsDoc Toolkitのインストールについては、こちらを参照してください。

ドキュメント生成のためのコメント(ドックコメントと呼びます)記法はJavaDocをベースにしており、比較的容易に習得することができます。ドックコメント付きのソースコードと、そこからJsDoc Toolkitによって生成されたドキュメントのスクリーンショットを下に示します。
+ << クリックするとソースコードを展開します...
/**
 * 新しいStringBufferオブジェクトを作成する。
 * @class 文字列をバッファリングし、文字列の効率的な結合を行うクラス
 * @param {String} [str] バッファリングする文字列
 * @example alert(new StringBuffer("このように").append("文字列を").append("結合します。").toString());
 */
function StringBuffer(str) {
    /**
     * バッファされている文字列の配列
     * @type String[]
     * @private
     */
    this._str = str?[str]:[];
}

/**
 * バッファに文字列を追加する。
 * @param {String} str バッファリングする文字列
 * @return {StringBuffer} このオブジェクトへの参照
 */
StringBuffer.prototype.append = function(str) {
    this._str.push(str);
    return this;
};

/**
 * バッファリングされた文字列を結合して返す。
 * @return {String} 結合された文字列
 */
StringBuffer.prototype.toString = function() {
    return this._str.join("");
};
- << クリックするとスクリーンショットを展開します...
  • ドックコメントの書き方については、こちらを参照してください。
  • ドキュメントの作成手順については、こちらを参照してください。

JsDoc Tooikitの特徴のひとつは、独自のテンプレートシステムによるドキュメント表示形式の柔軟性です。テンプレートはスキンのようなもので、JsDoc Tooikitのコア機能である構文解析機能から完全に独立しています。このためユーザはテンプレートを切り替えることで、JsDoc Tooikitのソースコードに手を入れることなく独自のドキュメントスタイルを利用できるようになっています。
例えば上に挙げたソースコードを管理人が作成したテンプレートaias-frameを使って出力すると、次のようになります。
- << クリックするとスクリーンショットを展開します...
  • テンプレートなどによるJsDoc Toolkitのカスタマイズについては、こちらを参照してください。
  • 管理人が作成したテンプレートなどをこちらからダウンロードできます。


リンク



目安箱バナー