【訂正エントリ】jsdoc3の使い方が間違ってると指摘を受けたので再評価した

以前、JavaScriptのAPIドキュメント生成ツールを調べてみたら、YUIDocが割とよかった - DenkiYagiというエントリで「jsdocゴミっぽい」と書いたのだが、「それアノテーションの使い方が間違ってる」とツッコミが入ったので、再評価してみた。

インストール

jsdoc3本体のほかにJava(JRE)が必要。

GitHubにはnpmでのインストールコマンドも書いてあったので、てっきりNode.jsでも動くのかと思ったのだが、よく見たら"JSDoc does not currently run on Node.js"って書いてあった。なんでNode.jsで動かないものをnpmで配布してるのかはちょっと意味が分からなかった。

ドキュメント生成対象コード

以前のエントリからの変更点は、@moduleではなく@namespaceに変えたのが大きなポイント。jsdoc3では、@moduleはCommonJS/Node.jsのモジュール（ファイル）を対象にするもので、以下のようなコードの場合は@namespaceを使うのが正解とのこと。

/**
@namespace
*/
var sample = {};
(function () {
    /**
    Observer Pattern: Observable class
    @alias sample.Observable
    @memberOf sample
    @constructor
    **/
    function Observable() {
        /**
        @property _observers
        @type {Array}
        @private
        */
        this._observers = [];
    }
    
    /**
    Add Observer.
    @param fn {Function} Observer
    **/
    Observable.prototype.add = function (fn) {
        var index = this._observers.indexOf(fn);
        if (index < 0) this._observers.push(fn);
    }
    /**
    Remove Observer.
    @param fn {Function} Observer
    **/
    Observable.prototype.remove = function (fn) {
        var index = this._observers.indexOf(fn);
        if (index >= 0) this._observers.splice(index, 1);
    }
    /**
    Notify all observers.
    @protected
    **/
    Observable.prototype.notify = function () {
        for (var i = 0, len = this._observers.length; i < len; ++i) {
            this._observers[i]();
        }
    }
    
    sample.Observable = Observable;
})();

気になった点(1)

@namespaceを付けないと即時関数内のコメントはすべて無視する（ある程度、構文を見てドキュメント生成を行う）挙動は相変わらずだった。即時関数内にグローバルクラスを書いた場合、@globalとかを付けてもコンストラクタしか拾ってくれなかったり、意図通りにドキュメントを生成できなかった。なのでやはりコードをの書き方をjsdoc3の都合に合わせる必要があり、俺様OOPなどの特殊な書き方をしてる場合はうまくドキュメントが生成できなさそうな気配がある。

気になった点(2)

コマンドラインオプションで -p を指定しないと@privateが無視されてしまう。

jsdoc3を再評価してみて

以前は不燃ごみと書いたが、単に私がアノテーションの書き方を間違えてただけで大抵の場合はちゃんと動くので、これは訂正したい。ただ、前述の気になった点(1)で書いたように、jsdoc3が想定していないコードの書き方をしていると意図したとおりにドキュメントを生成してくれないケースがある（大抵は問題がないのだけど）のは大きなマイナスポイントだと思う。

私が使うかと言われたら、強制されない限りは使わないなぁ。焼き土下座エントリにするつもりだったのだけど、評価した結果はそうはならなかったです。