2010年5月5日水曜日

Jsdoc-ToolkitをExtendScriptで試す

Jsdoc-toolkitという、JavaDocのようなドキュメント生成ツールがある。
それをExtendScriptで使えないか、ずっと試そうと思ってたんだけど、GW休みになってようやく試す事ができたのでメモ。

Jsdoc-toolkitは、JavaDocと似た文法でJavaScriptのソースコードにコメントを書くと、それからHTMLのドキュメントを書き出してくれるフリーウェア。
JsDoc Toolkitを使う!
を参考にさせてもらう。上記ページにほとんどのことは書いてあるので、ドキュメントの記述方法など、詳しい事はそちらを参照して下さい。

手順としては、
1.Javaのインストール
これはMacには標準で入っているのでOK。

2.JsDoc-toolkitのインストール
http://code.google.com/p/jsdoc-toolkit/downloads/list
から最新のjsdoc_toolkit-x.x.x.zipを落として解凍し、任意の場所に置く。
(自分の習慣として、こういうのは/optに置いています。)

3.とりあえずドキュメントを用意
http://www12.atwiki.jp/aias-jsdoctoolkit/pages/13.html
のサンプルコードをテスト用に、そのままコピってくる。jsxなので#targetとか入れてみる。
#target "Illustrator"
/**
* 数値に1を加算して返す。
* @param {Number} num 数値
* @returns {Number} 引数で与えられた数値に1を加算した数値
*/

function incrementNumber(num) {
return num + 1;
}
これを
~/Desktop/jsdoctest/jsdoctest.jsx
に保存する。

4.コマンド実行
$ cd '/opt/jsdoc-toolkit/'
$ java -jar jsrun.jar app/run.js /Users/kanemu/Desktop/jsdoctest -x=jsx
-t=templates/jsdoc/ -d=/Users/kanemu/Desktop/jsdoctest/jsdoc
-xオプションは拡張子の指定。.jsならば入れなくても書き出すが、.jsxを書き出すためには-xオプションで指定しなければいけない。
-tオプションはHTMLテンプレート。これはJsdoc-toolkitに付属しているものを使うが、カスタマイズもできるみたい。
-dオプションは書き出し先の指定。

これでターミナルから実行すると……

できた!こんなふうに、ドキュメントが生成される。
いくつか試したが、ExtendScriptだからってとくにエラーを出すでもなく、きれいに行った。いいんじゃないかな?


さて、いちいちコマンドを打つのは面倒なんで、もっと簡単な方法はないかと、Antを使った方法(jsdoctoolkit-ant-task)なんかをいろいろ試したが、あんまり上手くいかなかったので割愛。

自分はスクリプトを書くのにTextMateを使っているので、それのバンドルがないかと思って探したら、見つけた。
jsdoctoolkit-tmbundle
これを試してみる。ターミナルから、
$ cd ~/Library/Application\ Support/TextMate/Bundles/
$ git clone http://github.com/choan/jsdoctoolkit-tmbundle.git Jsdoctoolkit.tmbundle
これでTextMateを立ち上げると、Bundleが入っている。Jsdoc-Toolkitも一緒に入るので、別にインストールしたものは削除してしまって良い。

ただ、このままだと.jsxの拡張子に対応しないので、Bundle EditorでJsdocToolkitバンドルの"Create Docs"の下の方にある
java -jar "${JSDOC_DIR}/jsrun.jar" "${JSDOC_DIR}/app/run.js" -a
-t="${JSDOC_DIR}/templates/jsdoc" -d="${DOCS_DIR}" -r .
の行を
java -jar "${JSDOC_DIR}/jsrun.jar" "${JSDOC_DIR}/app/run.js" -a
-x="js,jsx" -t="${JSDOC_DIR}/templates/jsdoc" -d="${DOCS_DIR}" -r .
に変更。

あと、Scope Selectorの「source.js」はJavaScriptバンドルの方で記述されているので、
JavaScriptバンドルの"JavaScript"の上の方の行
fileTypes = ( 'js', 'htc' );

fileTypes = ( 'js', 'jsx', 'jsxinc', 'htc' );
に変更。これで Bundles>JsDoc Toolkit>Cleate Docs を実行すれば、JsDocが生成される。

満足!これからはがんばってドキュメント書くぞ!

20100509追記:
もう一つ。jsdoctoolkit-tmbundleを入れているとjsdocの
/**
*
*/
が/*+tabで入力できるのだが、これの中でreturnを押すと行頭に * のついた行が1行増える。英語環境なら良いのだけど、CJK-Input.tmpluginを入れて日本語を使っていると、エンターで変換できなくなっちゃう……。
なので、 jsdoctoolkit-tmbundleの "Newline"の、入力補完をreturnからshift+returnに変更。これでjsdocの中も日本語入力可能に。

0 件のコメント: