墜落日記 - 2009年12月15日の墜落

JsDoc Toolkit を使ってみる

修羅場ってた仕事も一段落しつつある今日この頃、やっと自分の趣味の開発に夜の時間を割ける様になってきた。
で、今はシコシコと JavaScript のライブラリを書いてみていたりする。
元々は仕事の絡みで、JavaScript 上で非同期処理をやれると便利な局面に出会ったのがキッカケ。
ウィンドウプロシージャの様にある処理が行われるまでを延々と無限ループして待機し続けることが出来れば良いだけだったのだけど、ま～ユーザエージェントの JavaScript を知っている人なら直ぐに分かるだろう。

単純に無限ループを書いてしまうと、ブラウザがハングるのである。

と言うのも、JavaScript は基本的にシングルタスク前提。
setTimeout 関数なんかで割り込んでいる様に見えるけど、実はアレも別の JavaScript の処理の実行中には割り込んでこない。
挙動を見る限りでは、ユーザインターフェイスのためのメッセージキューがあって、クリックなどのイベント処理や setTimeout 関数なんかのイベント処理は全てキューを経由して処理されるらしい。（間違っているか？）
で、キューに溜め込まれたメッセージを順に処理していく形で全体が動いていて、キューとキューの間に処理が割り込んだり、キューの実行中に別のキューが走り出したりというのは基本的に出来ない様だ。
だから、待ち時間 0 で setTimeout 関数を利用してみても、その直後に 1000 ミリ秒かかる処理があれば割り込みはキッカリと 1000 ミリ秒後なのだ。

で、仕事では取り敢えず期限があるので非同期処理ではなく別の方法を使ったのだけど、JavaScript で非同期処理と美しく無限ループを記述する方法を試行錯誤してみたわけである。
で、色々な実装をコードリーディングしてみたりしつつ、人が書いたライブラリをそのまま使うんじゃ面白くないから俺テイストで書き起こしてみた。
（結局のところ JSDeferred 風味になっちゃったけどね）

ま～その成果物はそのうちに公開することとして………

ここまでは壮大な前振り（おひ）

そんなこんなで JavaScript のライブラリが最近ちょこちょこ大きくなってきた。
興味が出る度に作っては増やししているので、関連性の薄い機能が混在する状態にもなっており、自分的に美しくない。
なのでモジュール分割して、オブジェクトを名前空間と自己暗示したりしてみたりするのだけど（JavaScript 的には割と常套手段）、今度はモジュール間の関連性なんかが見通しが悪くなるし、エディタのアウトライン機能だけ使っても把握しづらくなってしまう。

頭に入っているウチは良いけど、自分のコードだって弄らなくなったら３ヶ月程度で忘れちゃう(汗々)
もちろんこんな状態で第三者が使ってみるなんて夢の又夢なので、ドキュメントを作っておきたい。
だけどコードと分離したドキュメントはずぼらな自分は絶対にメンテナンスしなくなる………なので JavaDoc の様なドキュメント生成ツールを探してみた。

そうするとやっぱしあるのである、JavaScript 用のドキュメント生成ツール JsDoc Toolkit が。

JsDoc Toolkit は JavaScript 用のドキュメント生成ツールだ。
JavaDoc の様にコード上に記述したコメントを拾い集めて出力してくれる。
標準ではシンプルな XHTML 形式のドキュメントを出力するテンプレートが添付されていた。

で、JsDoc Toolkit を試してみたのだけど………

割とお手本的なオブジェクト指向言語である Java と、オブジェクト指向的な記述も出来るけどプロトタイプベースの JavaScript では、似た様な書き方は出来ても非なる物。
JsDoc Toolkit での出力結果に必要充分な情報を乗せるためには、JavaDoc よりも慎重かつ多くのタグ付けが必要な様だ。
ただソレさえなんとか乗り越えてしまえば割と良く動いているみたいである。

難点を上げるとすれば、JavaScript のソースをパースする部分と、テンプレートを通して HTML などに出力する部分が明確に別れているせいか、記述ミスの追跡が非常しにくいこと。
警告ログ自体は出るには出るのだけど、どのファイルの何行目の記述で警告になったのか判然としないので、一度に大量のスクリプトをパースすると愕然とする。
JsDoc Toolkit を利用するなら、最初から利用することを前提に、ちょこちょこ出力して結果を確かめておいた方が良いかもしれず。

他にも難点があって、標準で最初から付いているテンプレートがあまりにも杜撰な造りをしている。
スタイルシートの定義も不充分で、Internet Explorer 6.0 だとレイアウトが崩れるとか、色々と厄介。
JavaScript のコードをハイライトして出力するプラグインも「行数が 999 越えたらどうすんじゃいっ！？」って感じの拙い設計だし。
なので、テンプレートとコード出力プラグインは実用上問題ない程度には直してしまう。
（ま～その為の叩き台程度に考えた方が良いだろう）

あと、最大の難点は JavaScript がネットワーク経由でやりとりされる前提だという部分だろうか？
要はファイルサイズが JsDoc Toolkit 向けのコメントを入れるだけでエライ膨らむのである。
トラフィックが気になる規模の開発ではこの辺りはハッキリと割り切って、メンテナンス・開発用のソースと、コメント回りを削除したりして小型化した本番運用用のソースを分離した方が良いかもしれない。
（もちろん本番運用の為のソースは再現可能な手続きでの自動生成が前提だ）

取り敢えず、拙い物だけど出力してみたドキュメントを晒してみる。