mog project: Generate Documentation for JavaScript

JavaScript のドキュメントを自動生成する

JavaDoc とよく似たシンタックスで、JavaScript のドキュメントを生成できる jsdoc-toolkit というツールがある。

Google のスタイルガイドに従って JSDoc 形式でコメントを記述すれば、より開発効率が向上するはずだ。
http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=JavaScript_Types#Comments

1. コメントの記述

ポイントとなる部分だけ以下に紹介する。

ファイルレベルのコメント

主な JSDoc タグ

@fileoverfiew 説明文
@author メールアドレス (名姓)

説明文は複数行にまたがっても、インデントしない。

例)

/**
 * @fileoverview ファイルレベルのコメントをここに書く。
 * JSDocのサンプル。
 *
 * @author example@example.com (Mog Project)
 */

クラスへのコメント

主な JSDoc タグ

@param {型} コンストラクタ引数(仮引数)の名前説明文
@constructor

コンストラクタ引数を取る場合は @param を引数の個数分作成する。
また、コンストラクタであることを明示するため @constructor を付ける。

型の表記については Google スタイルガイドを参照。
http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=JavaScript_Types#JavaScript_Types

例)

/**
 * JSDocサンプル用クラス
 *
 * @param {string} id タグの識別名
 * @param {string} description タグの説明
 * @constructor
 
 */
var JSDocSample = function(id, description) {
  /* ... */
};

メソッド・関数へのコメント

主な JSDoc タグ

@param {型} 仮引数の名前説明文
@return {型} 説明文
@private

処理の概要、パラメータ、戻り値の説明を書く。

説明文が長くなった場合(1行80文字以内に収まらない場合)は、次の行は半角スペース4文字でインデントする。
プライベートなメソッド・プロパティ名には @private を付ける。
説明文においては、JavaDoc 同様、いくつかのHTMLタグがサポートされる。

例)

/**
 * メッセージを補完して返す。
 *
 * @param {string} msg 補完するメッセージ
 * @return {string} このように説明が長～～～～～～～～～くなった場合は、
 *    スペース4文字でインデントして続ける。
 */
JSDocSample.prototype.getInfo = function(msg) {
  var s = this.decorate_(['*', msg, '*']);
  return this.id + '(' + this.description + '): ' + s;
};

/**
 * 文字列を装飾する。
 *
 * @param {Array.<string>} arr 対象文字列の配列
 * @return {string} 装飾後の文字列
 *     <ul>
 *     <li>こんな風に
 *     <li>HTMLタグも
 *     <li>使用可能
 *     </ul>
 * @private
 */
JSDocSample.prototype.decorate_ = function(arr) {
  return arr.join('+');
};

プロパティへのコメント

主な JSDoc タグ

@type{型}

プロパティの説明と型を記述する。

例)

  /**
   * ID情報
   * @type {string}
   */
  this.id = id;
  /**
   * 説明テキスト
   * @type {string}
   */
  this.description = description;

2. ドキュメントの出力

Java 実行環境の準備

JRE 6以上を推奨。

jsdoc-toolkit のインストール

こちらのサイトからツールをダウンロード。
jsdoc-toolkit - A documentation generator for JavaScript. - Google Project Hosting
http://code.google.com/p/jsdoc-toolkit/

ファイルを解凍し、適当なディレクトリ配下に配備。

ドキュメント生成

jsdoc-toolkit のインストール先ディレクトリへ移動後、
「java –jar jsrun.jar app/run.js」のパラメータに以下を指定して実行。

JavaScript ソース格納ディレクトリ
-t テンプレートディレクトリ ※必須
-d ドキュメント出力先ディレクトリ
-e 文字コード指定 (デフォルトはUTF-8) ※例) -e=shift-jis
-r 対象のソースを探索する深さを指定
-a コメントのないメソッド・関数も出力
-p @private 指定の定義も出力

実行例

java -jar jsrun.jar app\run.js (ソース格納ディレクトリ) -t=templates\jsdoc -d=(ドキュメント出力先ディレクトリ) -a -p

ドキュメント出力例

3. テンプレートの変更

ドキュメント生成時に異なるテンプレートを指定することで、ルックアンドフィールを自由に変えることができる。
サンプルを一つ紹介する。

Jsdoc2-template-bootstrap

Twitter bootstrap ベースのスタイリッシュなテンプレート。

テンプレート一式をダウンロード
http://orgachem.github.com/JsDoc2-Template-Bootstrap/index_jp.html
解凍し、jsdoc-toolkit\templates 配下に配備
例) jsdoc-toolkit\templates\JsDoc2-Template-Bootstrap
ドキュメント生成コマンドにて、テンプレート指定 (-t) のパスを変更
例) -t=templates\JsDoc2-Template-Bootstrap

ドキュメント出力例

References

Google JavaScript スタイルガイド - 日本語訳 - JSDocコメント
http://www38.atwiki.jp/aias-jsstyleguide2/pages/14.html

JsDoc Toolkitを使ってJavaScriptのAPI仕様書を作る（環境構築から出力まで）｜クラスメソッド開発ブログ
http://dev.classmethod.jp/etc/jsdoc-toolkit-compile/

JsDoc Toolkitによる開発効率向上を目指して－＠IT
http://www.atmarkit.co.jp/fcoding/articles/jsdoc/01/jsdoca.html

mog project

1.03.2013

Generate Documentation for JavaScript