読者です 読者をやめる 読者になる 読者になる

JavaScriptのAPIドキュメント生成ツールを調べてみたら、YUIDocが割とよかった

JavaScript document

JavaScriptAPIドキュメント生成ツール(いわゆるjavadocみたいなもの)を使いたくなったので、色々調べてみた。

jsdoc3

使い方が間違ってると指摘されたので、訂正エントリ書きました → 【訂正エントリ】jsdoc3の使い方が間違ってると指摘を受けたので再評価した - DenkiYagi

JavaScriptAPIドキュメント生成ツールは現在もjsdoc系が主流のようなので、その最新系統のjsdoc3をまず試してみた。

zipをダウンロードして展開すると、JREさえインストールされていればすぐに使える(Rhinoのjarが同梱されている)。

で、実際に使ってみたのだが、以下のように即時関数内にドキュメントコメントを書いているケースではドキュメントが正常に生成されない。

/**
@module SampleModule
*/
var SampleModule = {};
(function () {
    /**
    Observer Pattern: Observable/Subject class

    @class Observable
    @constructor
    **/
    function Observable() {
        /**
        @property _observers
        @type Array
        @private
        */
        this._observers = [];

        /**
        @property _value
        @private
        */
        this._value = null;
    }
    SampleModule.Observable = Observable;

    // 以下略
})();

どうやら即時関数内のドキュメントコメントは無視してしまうようだ。コードの書き方、コメントの付け方を工夫すれば回避できるようだが、本末転倒な感じがするので、即座に捨てた。

なんでこんな不燃ゴミが主流派になってるのだろう。

jsdoc toolkit

即時関数内のドキュメントコメントが無視されてしまう問題はjsdoc3だからなのかと思い、古いツールであるjsdoc toolkitを試してみたが、同様だった。
jsdoc系、ほんとゴミだな。

Natural Docs

動かしてみようかとおもったけど、Perlをインストールしろと言われて、めんどくさくなったので試すのをやめた。

Docco

非常に良いツールなのだけど、APIドキュメントではないなと思い試していない。でもいつか使ってみたい。

YUIDoc

で、最終的にここに至った。昔はPythonで動いていた気がするのだけど、今はnode.js化されていて、npmで簡単にインストールできるようになっている。

即時関数内のドキュメントコメントもちゃんと拾ってくれるし、コメントが書かれているソース行番号も拾ってくれるので良い感じ。デフォルトテンプレートの見た目はあまり好みではないのだけど、まぁガッツリ使うときはカスタマイズできる部分だし、良いかなと。

ということで、しばらくはこれを使っていく予定。