2013年12月08日

JSDuckからコードの情報を生成する

JSXアドベントカレンダードキュメントアドベントカレンダーのネタです。

Ext.jsというJavaScriptのGUIフレームワークがあります。流行り廃りの早いウェブ関連の世界では比較的長い歴史を持ち、それゆえにIE 6.0から最新ブラウザまで対応しつつ、豊富なコンポーネントを備えたフレームワークとなっています。クラス数は数百あります。モバイル向けのSencha Touchもあります。Sencha Touchパーフェクトガイド という日本語の本もリリースされています。網羅的に書かれていて、バックエンドにDropboxを使う方法とか、モバイルの周辺をきちんと抑えてある本ですのでオススメです。

Ext.jsなどのプログラムには、GUIというとクラスがたくさん登場します。この型というものがライブラリにすでにたくさん定義されているのに、プログラミング時にそれを生かさないのはもったいないです。Ext.jsはドキュメント生成にJSDuckというツールを使っています。JSDuckには--export=fullと付けるとJSONでファイルを生成する機能があります。

$ jsduck --export=full --output st_jsonout ~/touch/src/

JSONには、クラスのメンバーとかいろいろ情報が含まれていますし、HTMLのドキュメントとかも含まれています。JSDuckで生成すると、独立した1ページのドキュメントが複数出力されるわけではありません。ajax的なページ片が生成されて、一部ずつロードされるようなファイルが生成されます。ブラウザの中にタブが出てきて、複数のクラスを同時に閲覧したり・・・というのはこういったバックエンドの仕組みに支えられています。

さて、クラスの情報が出力されたら、それを元に開発に使える形にします。ここで登場するのがJSXです。JSX用のラッパーができたら、コードを書いてコンパイルすればエラーチェックとかができちゃいます。それではJSONからJSXラッパーを生成するようなツールを用意しましょう。JavaScriptはフリーダムすぎる言語で、どのドキュメントツールもセマンティックスを付与できるようにたくさんのタグが提供されています。JSDuckも例外ではありません。また動的言語ということで、コールバックの返り値に対する説明が省略されがちだったりという問題もありますし、ドキュメントの型が一部間違っているということもありえます。コードコメントから生成ツールを作る場合には、元コードへのコミット権がないのであれば、ドキュメントに足りない説明を後から付与できるようにする必要があるでしょう。

それではツールを作ってみましょう。はい、できました。JSDuck2JSXというのがこのためのツールです(ここで頭のなかで3分クッキングのBGMを想像してください)。これで生成したテンプレートを使えば、GUIをJSXで生成できるようになります。ただし、Ext.jsのクラスの仕組みが複雑怪奇すぎるので、モデルとか気の利いた機能はまだ使えないです。ここはなんとかしたいところ・・・このコードを修正したら、HaxeとかTypeScript用のラッパーも作れるかもしれません(他の人がメンテするのは考えてないコードになってますが)。もちろん、手でラッパーを書くのも場合によっては悪くない選択肢になります。node-redis なんかはAPIは自動生成でシグニチャに関する情報がコード中に全然ないので、使い勝手の良いJSXラッパーを作るには手書きしかないでしょう。逆に、今回のSenchaの場合はクラス数が500を超えるので手で書くのは現実的ではないです。

ドキュメントを読むのは人間だけじゃないよ、というお話でした。

当初、ドキュメントアドベントカレンダーに登録した時にこちら用に書いた記事でしたが、Doc-jaという似たアドベントカレンダーを見て、「あれ?登録したはずなのにないや、JSXの方に流用しちゃえ」とそっち向けに公開しました。その後間違えに気づいたので、元のアドベントカレンダーの方にも登録しました。関係者のみなさん、ごめんなさい。原稿は11月中に書いて12/8時限公開設定してたよ、落としたわけじゃないよ。
posted by @shibukawa at 00:00 | TrackBack(0) | 日記 はてなブックマーク - JSDuckからコードの情報を生成する
この記事へのトラックバックURL
http://blog.sakura.ne.jp/tb/81113387
※ブログオーナーが承認したトラックバックのみ表示されます。

この記事へのトラックバック
検索ボックス

Twitter

www.flickr.com
This is a Flickr badge showing public photos and videos from shibukawa.yoshiki. Make your own badge here.
<< 2016年06月 >>
      1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30    
最近の記事
カテゴリ
過去ログ
Powered by さくらのブログ