TypeScriptのAPIドキュメントをyuidocjsで自動生成 - 成らぬは人の為さぬなりけり

現在、仕事でTypeScriptを使っていますが、
APIドキュメントが欲しくなってきて、
JavaDocとか、RDocとか、ScalaDocとか、みたいに
自動生成させたいなぁと思い、いろいろ試してみました。

試したツール

jsdoc (npm)
JsDoc Toolkit
jsduck (gem)
yuidocjs (npm)

試した結果

jsdoc : module以下のクラスのdocが生成できなかった
JsDoc Toolkit : jsdocと同じ
jsduck : docに定義されているタグが足りないとエラーになる
yuidocjs : module以下のクラスもdoc生成できた

と、いう訳で、yuidocjsを使ってドキュメント生成することにしました。
以下、環境構築手順と使い方についてメモしたいと思います。

環境

MacOSX 10.8.3
npm 1.2.14
typescript 0.9.0
yuidocjs 0.3.44

※typescriptは0.9.0ですが、以下の内容は0.9.0の機能には依存していません。

今回の流れ

TypeScriptのインストール（バージョンアップしたかったので）
yuidocjsのインストール
TypeScriptのコードを書く
docコメントを書く
TypeScriptコンパイル
yuidocjsの設定
yuidocjsでドキュメント生成

TypeScriptのインストール

$ sudo npm install -g typescript

yuidocjsのインストール

$ sudo npm install -g yuidocjs

TypeScriptのソースを書いてコンパイル

今回は複数のtsファイルがある事を想定
moduleを使っている事を想定

という前提で書いてみます。（コードの内容に深い意味はありません。）

src/App.ts

/// <reference path="util/Hoge.ts" />
class App {
    private hoge: Util.Hoge;
    constructor(hoge: Util.Hoge) {
        this.hoge = hoge;
    }
    start(): void {
        this.hoge.say();
    }
}

src/util/Hoge.ts

module Util {
    export class Hoge {
        say(): void {
            console.log("hoge");
        }
        say2(): void {
            console.log("hoge2");
        }
    }
}

docコメントを書く

では、早速上記のコードにdoc生成の為のコメントを書いていきます。
※以下に書く内容以外の書き方に関しては、こちらを参照してください。

src/App.ts

/// <reference path="util/Hoge.ts" />
class App {
    private hoge: Util.Hoge;

    /**
       @class App
       @constructor
       @param {Util.Hoge} hoge
    */
    constructor(hoge: Util.Hoge) {
        this.hoge = hoge;
    }
    /**
       @method start
    */
    start(): void {
        this.hoge.say();
    }
}

src/util/Hoge.ts

module Util {
    /**
       Hogeるクラスです
       @class Util.Hoge
    */
    export class Hoge {
        /**
           hogeって言います
           @method say
        */
        say(): void {
            console.log("hoge");
        }
        say2(): void {
            console.log("hoge2");
        }
    }
}

※say2にはコメントを書いていません。

TypeScriptをコンパイル

$ tsc src/App.ts --out src/App.js -c

今回は、

コンパイル後のファイルを1ファイルにまとめたい
コンパイル後のソースにコメントを残したい

ということで、
--outと-cというオプションをつけました。
※他のオプションに関しては、こちらをどうぞ。

これで
src/App.js
というファイルができたはずです。
中身を見てみましょう。

var Util;
(function (Util) {
    /**
    @class Util.Hoge
    */
    var Hoge = (function () {
        function Hoge() {
        }
        /**
        @method say
        */
        Hoge.prototype.say = function () {
            console.log("hoge");
        };
        Hoge.prototype.say2 = function () {
            console.log("hoge2");
        };
        return Hoge;
    })();
    Util.Hoge = Hoge;
})(Util || (Util = {}));
/// <reference path="util/Hoge.ts" />
var App = (function () {
    /**
    @class App
    @constructor
    @param {Util.Hoge} hoge
    */
    function App(hoge) {
        this.hoge = hoge;
    }
    /**
    @method start
    */
    App.prototype.start = function () {
        this.hoge.say();
    };
    return App;
})();

こんな感じになっているかと思います。

yuidocjsの設定

yuidocjsはyuidoc.jsonというファイルを作って、設定を書く事ができます。
※もちろんコマンドの引数に渡してもOKです。

今回はこちらのサンプルを参考に以下のようにしてみました。

{
    "name": "SampleApp",
    "description": "document sample",
    "version": "0.0.1",
    "url": "http://straitwalk.hatenablog.com/",
    "options": {
        "linkNatives": "true",        
        "attributesEmit": "true",
        "selleck": "true",
        "paths": "src",
        "outdir": "./doc"
    }
}

ちなみに、pathsにsrc/*.jsとか書くと

warn: (yuidoc): Paths argument was empty

と怒られて、生成が行われません。
ディレクトリを指定しないとダメっぽいです。
（ここで小一時間はまる、、、orz）

ここまで出来たら、後はコマンドを叩いてドキュメント生成して終了です。

yuidocjsでドキュメント自動生成

$ yuidoc

カレントディレクトリにyuidoc.jsonがあれば、
自動的に読んでくれるので、オプションは付けなくてもOKです。
※ログ出力を見たくなければ、yuidoc -q

生成結果を見てましょう！！

f:id:straitwalk:20130622022429p:plain
f:id:straitwalk:20130622022436p:plain
Util.HogeのAPIドキュメントにsay2がありません。
docコメントを書いてないメソッドは出力されないようです。

さて、今回はここまでにします。

おまけ

CreateJSのオンラインドキュメントってyuidocjs使ってるんじゃなかろうか。
EaselJS v0.6.1 API Documentation : EaselJS