アシアルブログ

こんにちは。松田です。

のほほーんとコーディングをしていると、「この辺のプログラム、どんな形式でもいいからドキュメント書いて出して」なんて突然言われて気が重くなっちゃうことがありますよね。プログラマーはドキュメントの作成がとっても苦手なので、「あぁ・・・もうコメント書いてASDocでHTML出力しちゃえばいいかな・・・」ということになりがちです。
そんなときに役立つ、FlashBuilderからASDocを簡単に生成する方法を紹介します。
これを設定しておけば、いつでもボタン一つでASDocが出力できます。

そもそもASDocって何？という話ですが、クラスやメソッドに付けたコメントを元に、見やすくHTML形式のドキュメントを出力してくれるものです。
簡潔に書くとこんな形式のコメントを使用します。

1. /** 
2. * Main comment text.
3. * 
4. * @tag Tag text.
5. */
6. public var .....

詳細なコメントのフォーマットは以下のURLを参照してください。
http://livedocs.adobe.com/flex/3_jp/html/help.html?content=asdoc_1.html



ASDocはFlexSDKがあれば作成可能で、本来はコマンドラインで動かすものらしいのですが、FlashBuilder（FlexBuilderでも）から簡単に作れるようなのでやってみました。

手順は以下の通りです。

1. メニューから「実行」→「外部ツール」→「外部ツールの構成」を選択



2. ウィンドウ内の左側のツリーの「プログラム」をダブルクリック



3. 新規構成画面が表示されるので項目を埋める


以下は今回の設定例です。

1. 名前： ASDoc

これはなんでもいいです。

1. ロケーション： C:\Program Files\Adobe\Adobe Flash Builder 4\sdks\4.0.0\bin\asdoc.exe

FlexSDKのディレクトリの bin/asdoc.exe を選択します。

1. 作業ディレクトリー： ${project_loc}

この文字列を書いておけば選択しているプロジェクトが自動的に使用されます。

1. 引数：
2. -source-path src
3. -doc-sources src

スクリプトを保存しているディレクトリ（ここではsrcディレクトリ）を指定。


4. 「適用」「実行」をクリック


5. ASDocを作成したいプロジェクトを選択した状態で、「実行」→「外部ツール」→「ASDoc」を選択



6. 成功すればプロジェクト内に「asdoc-output」が！



7. この赤丸のところのボタンを使っても実行できます。


生成に成功するとasdoc-output内に大量のファイルが生成されます。index.htmlがトップページになるのでそれを開きましょう。

8. こんな感じのHTMLができました！


項目が少なくてショボかったので適当なメソッドを追加してます。
スクリプト上で定義していない、「public var image:Image」なんてのが出力されて、何だこれ？となったのですが、これはMXML上でidを登録しているオブジェクトが自動的に表示されてるんですね。
なかなかかしこい。



そもそもコメント書いてないから今更書くのめんどくさい・・・
そんな場合、FlexFormatterプラグインが便利です。
ASDocを生成するには、ある程度決まった形式のコメントを付けておく必要がありますが、このプラグインの「Generate ASDoc comments」機能を使えば、各クラス・メソッド・変数に自動的にコメントを付けてくれます。

FlexFormatter
http://sourceforge.net/projects/flexformatter/

1. public function hoge(value1:int, value2:String):int {}

この状態で使用すると、

1. /**
2.  * 
3.  * @param value1
4.  * @param value2
5.  * @return 
6.  */
7. public function hoge(value1:int, value2:String):int {}

ここまでコメントを作ってくれます。
もちろん解説文は自分で入れる必要があります。
ちょっとだけ楽になりますね。

ただし、このプラグインは .asファイルにしか対応していないため、MXMLファイル内にASゴリゴリ書いている人は恩恵を受けられません。残念。



参照URL:
http://www.peterelst.com/blog/2009/06/08/flash-builder-4-beta-exporting-asdoc-documentation/