すたらブログ

文系Webプログラマの備忘録

JavaScript: JSDoc3を使い始めました

規則に沿って記述されたコメントを元に、簡単にHTML形式のAPIドキュメントを作ってくれます。
JSDocでAPIドキュメントを作成するには二通りの方法があって、Node.jsを使う場合とJava(Mozilla Rhino)を使う場合があるそうですが、私はJavaを選びました。
なお、導入までの手順はほぼ下記のページの受け売りです m(_ _)m

目次

  1. 環境
  2. JSDocをダウンロードする
  3. JSDocへのパスを通す
  4. Javaをインストールしてパスを通す
  5. (余談) 便利なタグ@lends

環境


JSDocをダウンロードする

公式のGitHubリポジトリからzipファイルをダウンロードして解凍し、適当な場所に設置します。
私はCドライブ直下にフォルダ名をjsdoc3と変更したうえで設置しました。
(C:\jsdoc3)


JSDocへのパスを通す

下記のようにしてパスを通します。(Windows7)

  1. コントロール パネルを開く
  2. システムとセキュリティ
  3. システム
  4. システムの詳細設定(サイドメニュー)
  5. 環境変数(ボタン)
  6. システム環境変数Path編集
  7. C:\jsdoc3を追加する。既存とはセミコロン;で区切ることを忘れずに。
  8. OKを押し続けてシステムのプロパティのウィンドウを閉じる

パスが通ったことを確認するためにヘルプを開いてみます。

コマンドプロンプト
jsdoc --help

Javaをインストールしてパスを通す

私の場合はすでにEclipseがあるのでJavaをダウンロードする必要はありません。
ただし、"java.exe"までパスを通す必要があります。
JSDocでパスを追加した方法と同じです。
私の場合はCドライブ直下にEclipseを置いているので、下記をPathに追加しました。
C:\pleiades\java\6\bin

これで準備完了です。 JavaScriptファイルがある階層で下記のように実行すればAPIドキュメントが作成されます。

コマンドプロンプト
jsdoc hoge.js

:: 階層を潜ってくれる -r オプションが便利です
jsdoc -r (フォルダ名)

(余談) 便利なタグ@lends

最近、私はクラスの継承を下記のように記述しています。

jQuery
// スーパークラス
function Class1(arg1, arg2) {
    this.prop1 = arg1 + arg2;
}
$.extend(Class1.prototype, {
    setProp1: function(arg) {
        this.prop1 = arg;
    },
    getProp1: function() {
        return this.prop1;
    },
});

// サブクラス
function Class2(arg1, arg2) {
    Class1.apply(this, arguments);
    this.setProp1(this.getProp1() + 10);
}
Class2.prototype = Object.create(Class1.prototype);
Class2.prototype.constructor = Class2;
$.extend(Class2.prototype, {
    meth2: function() {
        return this.getProp1() + 9;
    },
});

このとき、プロトタイプにメンバを追加している箇所をJSDocに理解してもらうためのタグが@lendsです。
オブジェクトリテラルの直前に記述することで、そのオブジェクトのメンバを、任意のクラスのメンバとして認識するそうです。

実際にはこのように書きます。

jQuery
/**
 * プロパティ"Prop1"を初期化する
 * @constructor
 * @classdesc 親クラス
 */
function Class1(arg1, arg2) {
    this.prop1 = arg1 + arg2;
}
$.extend(Class1.prototype, /** @lends Class1.prototype */ {
    /**
    * セッター
    * @param {number} arg Prop1に代入する数値
    */
    setProp1: function(arg) {
        this.prop1 = arg;
    },
    /**
    * ゲッター
    * @return {number} Prop1の値
    */
    getProp1: function() {
        return this.prop1;
    },
});
/**
 * 親クラスのコンストラクタの実行後に、プロパティ"Prop1"を更に加工する。
 * @constructor
 * @augments Class1
 * @classdesc Class1を継承したクラス
 */
function Class2(arg1, arg2) {
    Class1.apply(this, arguments);
    this.setProp1(this.getProp1() + 10);
}
Class2.prototype = Object.create(Class1.prototype);
Class2.prototype.constructor = Class2;
$.extend(Class2.prototype, /** @lends Class2.prototype */ {
    /**
    * クラス2の独自のメソッド
    * @return {number} 独自に加算した値
    */
    meth2: function() {
        return this.getProp1() + 9;
    },
});

@lends Class1と書くと、Class1のプライベートなメンバとして扱われてしまいます。
@lends Class1.prototypeと記述することで、APIドキュメントのClass2の項目で継承したメソッドとして掲載されます。

ちなみに、"lend" とは "貸す" という意味だそうです。