C9 Tech Notes: 2月 2011

Flash BuilderでASDocを使いたいと思い、いろいろと探したがどのサイトでも「外部ツール」としての登録による解説が多い。

しかしながら外部ツールでは以下のデメリットが発生する。

個別のPCに依存してしまう（他のPCでは設定のやり直し）

複数プロジェクトがある場合、個々に登録または随時設定変更する必要がある。

他のチームメンバーと共有できない

さっと作るだけならそれでいいが、上記のデメリットは大きい。

せっかくFlash BuilderはEclipseペースなのに強力なantを使わない手はない。

antベースに移行することで以下のメリットがある。

ビルドファイルを個別のプロジェクト毎に作成できる。

ソースコード管理へ含められる（他者と共有できる）

他の強力なAntタスクの処理と併用できる。

Flash BuilderにAntをインストールするための情報はたくさんあるのでそちらにゆずる。

antのexecタスクでasdocコマンドを直接起動する方法も多くのサイトで紹介されているがこちらの場合はパス環境等の問題を抱えることが多いようだ。

今回はせっかくなのでFLEX SDKにバンドルされているAnt用のAsDocタグを使った方法を紹介したい。

以下のビルドファイルを各プロジェクトのトップディレクトリに作成する。

build.xml


<?xml version="1.0" encoding="UTF-8"?>
<project name="OnyxPDF" basedir="." default="asdoc">


<property name="sdk.version" value="4.1.0"/>
<property name="sdk.dir" value="${eclipse.home}/sdks/${sdk.version}"/>
<property name="FLEX_HOME" value="${sdk.dir}"/>
<property name="src.dir" value="${basedir}/src"/>
<property name="doc.dir" value="${basedir}/doc"/>
<property name="lib.dir" value="${basedir}/lib"/>

<target name="asdoc">
　　　　
<available property="flexTasksJar" value="${sdk.dir}/lib/flexTasks.jar" file="${sdk.dir}/lib/flexTasks.jar"/>
<available property="flexTasksJar" value="${sdk.dir}/ant/lib/flexTasks.jar" file="${sdk.dir}/ant/lib/flexTasks.jar"/>
<taskdef resource="flexTasks.tasks" classpath="${flexTasksJar}"/>

　　　　
<asdoc output="${doc.dir}"
　　 lenient="true" failonerror="true"
warnings="false" strict="false" locale="ja_JP" fork="true"
main-title="ドキュメントタイトル"
window-title="ウインドウタイトル"
footer="フッター">
<doc-sources path-element="${src.dir}"/>

　　　　　


</asdoc>
</target>

<target name="clean">
<delete includeEmptyDirs="true">
<fileset dir="${doc.dir}" includes="**/*"/>
</delete>
</target>
</project>

プロパティ定義の部分は各自のプロジェクトの環境に合わせて変更する必要がある。

ここで注意したいのはsdk.dirおよびFLEX_HOMEのプロパティだ。

上記の設定はMac用に作成したもので、素直にSDKをインストールしていれば/Application/Adobe FlashBuilder 4/の下にFlex Sdkが展開されている。FlashBuilderのパスはexlipse.homeと同じなのでそれを使ってSDKのパスを指定している。

もちろん、SDKを独自の場所に設定している場合はそのパスを指定する必要がある。各PCでの環境依存を排除したいのであればbuild.properties等の別ファイルに記述し、それを読み込む（コメントアウト行）事で設定する。

このbuilder.propertiesのファイルをソースコード管理から外しておけばチームメンバーはそのファイルを修正するだけで利用することができる。

（このあたりはAntの活用方法なので他者にゆずる）

FLEX_HOMEというプロパティは必須プロパティで、必ずFlexSDKのパスを設定する必要がある。これは今回使用するasdocタグ等、Flex関連タグを使用する場合にこの名前でプロパティが設定されていないと実行時にエラーが発生する。

タスク定義の部分では、Flexのバージョンによってタスクタグのjarファイルの場所が違うため、availableタグを使って値を設定している。多くの場合は後者のパスなのでバージョンが固定されている場合はpropertyタグで直接定義してもかまわない。

その後のtaskdefタグで、Flex用のタグを読み込む。

asdocタグで重要な属性はoutputだ。こちらはドキュメントの出力先を指定する。

failonerror属性はエラー発生時に処理を中断するかどうかを設定。その他のlenient, warnings, strict等の構文解析の許容レベルを設定で、main-title, window-title, footer等は出力するドキュメントの各パートに表示する文字列を指定することができる。これらの設定の内容自体はasdocのコマンドラインオプションと同じなのでasdoc-help等を参照してほしい。

次にソースの指定だが、これはいくつかの方法があるが最も手っ取り早い方法は上記のようにディレクトリを指定する方式だ。

AsDocはある意味コンパイルすることと同じ処理を行うので、外部パッケージ等が解決できない場合はエラーが発生する。上記の例ではコメントアウトしているが、もし対象プロジェクトがswc等を使用している場合はexternal-libraryで指定する必要がある。また、AIRのライブラリを含めている場合は２番目の例のようにしてAIRのライブラリを取り込む必要がある。

AsDocの処理は重いためメモリが足りなくなる場合がある、その場合はjvmargタグで-Xmx512m等と調整すると解決できるかもしれない。

以上、ざっとした解説ではあるが、プロジェクトのASDocをantベースで生成するには上記のビルドファイルでも十分だろう。このasdocタグに関連する情報はネット上でも極端に少ない上、その設定は非常に多岐にわたる。（タグというよりasdoc自体のオプションが非常に多い）

より詳細な情報が欲しい場合は、FLEX SDKに含まれているSDK自体のドキュメント生成用のビルドファイルが非常に参考になるだろう。

$FLEX_HOME/asdoc/build.xml

その前に、ソースコードにコメントつけなければ何もはじまらないが（笑）