JavaScriptのドキュメント生成ツール、JSDoc3とYUIDocを比べてみた


Arctic.jsのドキュメントを英語化するべく、昨今のJavaScriptドキュメント化ツール事情を調べてみました。

今まではJSDoc2を使っていたのですが、これはJavaのインストールが必要であるのと、コマンドラインのインターフェースが分かりにくくて、あまり使い勝手が良くありませんでした。

そこで新たなツールに乗り換えるべく、近年代表的なJSDoc3YUIDocを比べてみます。

JSDoc3

JSDoc2の後継ですが、JavaScriptで書かれており、Node.jsかRhinoで動作します。インストールもnpmでサクッと行けます。ソースはこちら

利用方法

インストール

ドキュメント化コマンド

Gruntタスクとして使う

grunt-jsdoc-pluginを使えば、Gruntタスクとして使うことができます。

タスクの定義フォーマットは以下の様な形になります。

所感

– UIひどい(JSDoc2は良かった)

– UIのテーマをカスタマイズ可能。

– タグの種類が豊富で、様々なドキュメントの定義が可能。

 

YUIDoc

node.jsで書かれており、こちらもnpmでサクッとインストール出来ます。Live preview機能やマークダウンのサポートなど機能が満載です。ソースはこちらから

利用方法

インストール

ドキュメント化コマンド

このコマンドでカレントディレクトリ内の全jsファイルを走査しドキュメント化します。

Gruntタスクとして使う

gruntの公式pluginであるgrunt-contrib-yuidocが利用できます。

タスクの定義フォーマットは以下の様な形式です。

所感

– Live previewがとても便利です。Node.jsのサーバーをホストして、ファイルの変更がある度にドキュメント化を行ってくれ、最新のドキュメントをブラウザ上から素早く確認する事ができます。

– UIがなかなか良い。

– UIのテンプレートをカスタマイズ可能。

– jsdocにある@memberofのようなタグが無いので、クラス定義->メソッド定義の順番でコードが書かれている必要があり、クラス定義と離れた場所にメソッド定義等があった場合にドキュメント化できない。(と思われます。もし解決できる方法を知っていたら教えて下さい)

– ドキュメント化する対象をJSファイル単体で指定できず、フォルダを指定しなければならない。

 

まとめ

総合的にはYUIDocの方が断然イケてます。

ですが、僕の場合これまでJSDocのフォーマットでドキュメントを書いていたため、一部YUIDocで対応出来ない部分等があり、ソース自体を変更する必要が出てきそうだったため、JSDoc3を使ってテーマをカスタマイズする方針に決めました。

これからドキュメントのコメントを書き始める方には、YUIDocをオススメします!