ASDocを使ってみよう

書類作りは面倒くさい

　プログラムを作っていると自分でも何書いたんだか意図が分からなくなったりするので、コメントを書く。
　さらにプログラムが大きくなってくると、直接コードやコメントを追いかけるのも大変になってくる。
　そこで、ソースコードとは別に、オブジェクト毎の関数一覧などを作る事になる。
　一覧には外部からアクセスできない関数を書く必要はないので、かなりスッキリして分かりやすくなる。

　そういうば、そういうの見たことある、Adobeのサイトの AppleScript3 のクラスのヘルプだ。
　でも、そういう書類を作ること自体が、下手するとコーディングと同じくらいの労力になっちゃったりする。コード書き換えるたびに、書類も書き換えるとか、とてもやってられない。

　そこで「関数一覧は、こんな感じにフォーマットが統一してあった方が、見やすいね」ってことと、「ソースコードにコメントも関数も書いてあるんだから、そこから自動生成すればいいね」ってことから、ドキュメント(関数一覧)を自動生成するためのツールが作られるのは必然、という事になるわけだ。

　なるほど、つまりFlashにもそういうドキュメント生成ツールが附属してるんだか、そういう機能がメニューのどこかにあったりするんだね。
　となりそうなところだが、どーもそんなのはない(もしかしたら最新のFlash CCにはあるのかもしれないけど…ないよね)

　で、どーするかというと、Flexに附属してるから、それ使いましょう。同じActionScript3だから、なんとかなるんじゃない?

Flexを持ってこよう

　この開発日誌では、なんと一回だけFlexについて触れている。なんせFlexってツールは絵が描けないから、結局あんまり面白くなくて、それっきりだったりする。
　ドキュメント生成ツールのためだけに「Flash Builder」を買う意味はないので、無料の「Flex 4.6 SDK」にする。
　早速、Adobe の Flex SDK ダウンロードページに行って、ダウンロード。
　展開されたファイルを、適当なディレクトリ(私はApplications/Adobe/フォルダにした)に置く。

　そのドキュメント生成ツールはASDocと言うらしく、探すとflex_sdk_4/bin/フォルダにある、近くにasdocというそのまんまなフォルダもあるが、こちらは設定ファイルであって、asdoc本体ではないようだ。
　なお、ASDocによって生成されたドキュメントもASDocと呼んだりする。
　ついでに、ASDocはJavadocというJava言語用のドキュメント生成ツールをベースに開発されているようで、その記法はかなり似ている。

　binってのはバイナリ、つまり実行ファイルのことなんだけど、Mac OS Xの(ターミナル)シェル用の実行ファイルはbinの下に配置するのが作法。
　ここにある.exeと.batはwindows用なので捨てちゃう。逆にwinの人は、.exeと.batを残して後は捨てていい筈。
　なお、aasdocというasdocに似たファイルがある、これはAIR用のオプションをつけたasdocのシェルスクリプトで、今回はFlash CS6(Flash IDE)の通常のソースコードに対して使う予定なので、ひとまず無視。
　とは言え、自分が使いやすいように、asdocにオプションをくっ付けたシェルスクリプトを作っておくのは良さそうだ。

　コマンドラインツールなので、Mac OS Xに標準で付いてる「ターミナル」というアプリケーションを開いて、色々試す。
　デザイナーの延長でFlashを使っている人には、相当高いハードルだけど、既にアクションスクリプトは多少なりとも書いているわけなので、頑張ってターミナル(Mac OS X10.9.xではbashという種類)の使い方を調べて身につけていただきたい。
　というか、そういう私も、あんまり使ったことはなかったりする。
　こまごまと説明すると大変な事になるので、ざっと説明する。

　先ほど見つけたbinディレクトリにcdして、./asdoc -helpを見てみる。お、なんと日本語で表示された。詳細はさらにオプションを付けると表示されるらしい。
　んで今度は、./asdoc -help listとやると、ずらーーーーっと数画面分のオプションが表示された。やる気が失せる。良く読んだら、さらにadvancedとかもあるじゃん。なんだよそれ、オプションしこたまあるな。
　えーと、./asdoc -help list detailsすると、日本語(Shift JIS)による解説つきで、さっきのオプションが、ずらーーーっと表示される。この中で使うのって3つか4つがいいところなんだろーなー。
　GUIツールも付けてくれよ面倒くさい!! (Flexにはある気がするが)
　今後、頻繁に使う気がするので、Applications/Adobe/flex_sdk_4/bin/を$PATHに追加しておく。パス通したんで、もうどこからでも./無しのasdocで呼べる。

　さて、こんな感じで準備が整った。

では、ASDoc

　えー、適当なクラスファイル(例えばtest.as)を用意して、asdocに食わせてみよう。
　既にそのファイルがあるディレクトリにcdしているとして、オプション -doc-sources(省略形-ds)の後にファイル名を書けば良い。

asdoc -ds test.as

　ごりごりと動いて、ユーザディレクトリ直下にasdoc-outputディレクトリが生成された。生成場所は -output オプションで指定もできるらしい(「作成する SWF ムービーのファイル名」とかヘルプには書いてあるけど、swfは間違いだろー、だよね)
　その中のindex.htmlをブラウザで表示させて見ると、Adobeのサイトにあるのと同じ感じのHTML(他もろもろ)が生成される。
　ふーむ、思ったよりすんなり。

　ディレクトリを指定すると、そこに含まれるクラスを全部検索してASDocしてくれる。

asdoc -ds ./

　しかし、ここまですんなり行ったものの、その後、自前の(packageにディレクトリを設定した)ライブラリをimportしたクラスや、自前のライブラリクラス自身をASDocしてやろうとしたらよく分からんエラーが出て生成できない。
　ということがあって、5年(笑)ぐらい問題を先送りして、放ったらかしにすることになる。

そして、importが設定されている場合のASDoc解決

　そして時は流れ流れて、2014年。
　一時ほどFlashが流行らなくなって、なにかしらないけど奮起してASDocを勉強して、この記事を書いているというわけ。
　どうも私は「斜陽になってきたジャンルが大好き」っぽく、だいたいゲーム機を買うのもメーカーが生産中止宣言するかどうかというタイミングであることが多い。
　困ったものである。
　Flashで作ってるゲームからして、インタラクティブフィクション(文字だけでプレイするコマンドラインのゲーム)だもんな。

　さて、解決方法は、実は簡単だった。
　例えば、test.asのクラスの中で、デフォルトでないパッケージをimportしているとすれば、そのimportしているライブラリがあるディレクトリを、source-path(略称-sp)で指定してやればいい。

asdoc -ds test.as -sp /Users/myid/ActionScript3/lib/

　みたいな感じだ。この時注意するのは -sp で指定するのはライブラリのクラスファイルがある場所ではなく、ライブラリのルートであるということ。
　import jp.tonbi.test.TestClass;という感じで読み込んでいるなら、クラスファイルは/Users/myid/ActionScript3/lib/jp/tonbi/test/にある筈だが、このパスを指定するのではない、ということ。

packageが設定されているクラス自身のASDoc

　で今度は本命の、自作ライブラリクラスのASDoc。
　先ほどと同じようなことで、-spを指定しておけば良かったのだ。

asdoc -ds /Users/myid/ActionScript3/lib/jp/tonbi/test/TestClass.as -sp /Users/myid/ActionScript3/lib/

　ここで面白いのが、ドキュメント化対象のTestClassだけでなく、そこで使われているクラスなどの関連クラスも一緒にドキュメント化される。
　ちなみにその関連クラスも一緒にASDocする動作は、-exclude-dependencies falseでオフにできる。

　なお、-spが指定されている場合、その下のクラスはクラスパスによる指定もできる。
　オプションは -doc-classes (略称-dc)で、スラッシュ区切りじゃなくて、importとかで書くドット区切りで指定する。
　もちろん、拡張子.asもいらない。

asdoc -dc jp.tonbi.test.TestClass -sp /Users/myid/ActionScript3/lib/

おまけ

　参考までに、asdoc -help list detailsの結果を置いておく。多いよ!

-benchmark
    パフォーマンスベンチマークを出力します
-compiler.accessible
    エイリアス -accessible
    アクセス可能な SWF を生成します
-compiler.actionscript-file-encoding <string>
    エイリアス -actionscript-file-encoding
    ActionScript ファイルのエンコーディングを指定します。AS3 ソースファイルに BOM
    がない場合、コンパイラーはこのファイルエンコーディングを使用します。
-compiler.compress
    エイリアス -compress
-compiler.context-root <context-path>
    エイリアス -context-root
    サービスチャンネルのエンドポイントの {context.root} トークンを置き換えるパス
-compiler.debug
    エイリアス -debug
    デバッグに適したムービーを生成します
-compiler.enable-runtime-design-layers
    エイリアス -enable-runtime-design-layers
-compiler.extensions.extension [extension] [parameters] [...]
    エイリアス -extension
     (反復可能)
-compiler.external-library-path [path-element] [...]
    エイリアス -external-library-path
    コンパイル対象であるが、リンクからは除外される SWC ファイルまたはディレクトリの一覧 (反復可能)
-compiler.fonts.advanced-anti-aliasing
    エイリアス -advanced-anti-aliasing
    埋め込みフォントの高度なアンチエイリアスを有効にして、小さいフォントを見やすくします。
-compiler.fonts.flash-type
    エイリアス -flash-type
    埋め込みフォントの FlashType を有効にして、小さいフォントを見やすくする
-compiler.fonts.max-glyphs-per-face <string>
    エイリアス -max-glyphs-per-face
    各フォントについてサーバーにキャッシュできる文字のグリフアウトラインの最大数を設定します。デフォルト値は 1000 です。
-compiler.include-libraries [library] [...]
    エイリアス -include-libraries
    SWF に完全にインクルードされるライブラリ (SWC) の一覧 (反復可能)
-compiler.incremental
    エイリアス -incremental
    インクリメンタルコンパイルを有効にします
-compiler.library-path [path-element] [...]
    エイリアス -l
    SWC ファイルまたは SWC ファイルを格納するディレクトリの一覧 (反復可能)
-compiler.locale [locale-element] [...]
    エイリアス -locale
    国際化用にロケールを指定します (反復可能)
-compiler.minimum-supported-version <string>
    エイリアス -minimum-supported-version
-compiler.mobile
    エイリアス -mobile
    ターゲットランタイムがモバイルデバイスであることを指定します
-compiler.mxml.compatibility-version <version>
    エイリアス -compatibility-version
    互換性のあるバージョンを指定します (compatibility-version=2.0.1 など)
-compiler.mxml.minimum-supported-version <string>
-compiler.namespaces.namespace [uri] [manifest] [...]
    エイリアス -namespace
    MXML エレメントとして使用するためのコンポーネントのマニフェストに関連付ける URI を指定します (反復可能)
-compiler.omit-trace-statements
    エイリアス -omit-trace-statements
    trace ステートメントを省略するかどうかを切り替えます
-compiler.optimize
    エイリアス -optimize
    リンク後の SWF の最適化を有効にします
-compiler.preloader <string>
    エイリアス -preloader
    アプリケーションのプリローダー属性のデフォルト値を指定します。指定しない場合、デフォルトのプリローダー値は、-compatibility-version
    アプリケーションのプリローダー属性のデフォルト値を指定します。指定しない場合、デフォルトのプリローダー値は、-compatibility-version >=
    >= 4.0 のときに mx.preloaders.SparkDownloadProgressBar
    となり、-compatibility-version < 4.0 のときに
    mx.preloaders.DownloadProgressBar となります。
-compiler.report-invalid-styles-as-warnings
    エイリアス -report-invalid-styles-as-warnings
    無効なスタイルを警告として報告します
-compiler.services <filename>
    エイリアス -services
    Flex データサービス設定ファイルへのパス
-compiler.show-actionscript-warnings
    エイリアス -show-actionscript-warnings
    有効であるが部分的に正しくないコードを検出するモードで AS3 コンパイラーを実行します
-compiler.show-binding-warnings
    エイリアス -show-binding-warnings
    データバインディングコードから生成される警告を表示するかどうかを切り替えます
-compiler.show-invalid-css-property-warnings
    エイリアス -show-invalid-css-property-warnings
    無効な CSS プロパティに関する警告を報告するかどうかを切り替えます
-compiler.show-shadowed-device-font-warnings
    エイリアス -show-shadowed-device-font-warnings
    埋め込みフォント名がデバイスフォント名に影響する場合に、警告を表示するかどうかを切り替えます
-compiler.show-unused-type-selector-warnings
    エイリアス -show-unused-type-selector-warnings
    使用されていない CSS タイプセレクターから生成される警告を表示するかどうかを切り替えます
-compiler.source-path [path-element] [...]
    エイリアス -sp
    ActionScript クラス階層のルートを形成するパスエレメントの一覧 (反復可能)
-compiler.strict
    エイリアス -strict
    厳密なエラーチェックモードで AS3 コンパイラーを実行します
-compiler.theme [filename] [...]
    エイリアス -theme
    テーマとして適用する CSS または SWC ファイルの一覧 (反復可能)
-compiler.use-resource-bundle-metadata
    エイリアス -use-resource-bundle-metadata
    リソースバンドルがアプリケーションに含まれているかどうかを調べます。
-compiler.verbose-stacktraces
    エイリアス -verbose-stacktraces
    デバッグ用にコールスタック情報を SWF に保存します
-date-in-footer
    フッターに日付を含めるかどうかを指定します。
-doc-classes [class] [...]
    エイリアス -dc
    ドキュメントに含めるクラスの一覧。 (反復可能)
-doc-namespaces [uri] [...]
    エイリアス -dn
    ドキュメントに含める名前空間の一覧。 (反復可能)
-doc-sources [path-element] [...]
    エイリアス -ds
    ドキュメントに含めるソースファイルの一覧。 (反復可能)
-examples-path <string>
    サンプルファイルを検索するパス。
-exclude-classes [class] [...]
    ドキュメントから除外するクラスの一覧。 (反復可能)
-exclude-dependencies
    依存関係を除外するかどうかを指定するブール。
-exclude-sources [path-element] [...]
    ドキュメントから除外するソースファイルの一覧。 (反復可能)
-footer <string>
    ドキュメントに表示するフッター文字列。
-framework <string>
-help [keyword] [...]
    キーワードは 'syntax','list','advanced','aliases','details',または検索語句です
-include-all-for-asdoc
-left-frameset-width <int>
    左フレームの幅。
-lenient
    適格な形式の HTML エラーを警告として報告します。
-licenses.license <product> <serial-number>
    エイリアス -license
    製品とシリアル番号を指定します。  (反復可能)
-load-config <filename>
    設定オプションを含むファイルをロードします (反復可能)
-main-title <string>
    タイトルバーに表示するタイトル。
-metadata.contributor <name>
    エイリアス -contributor
    SWF メタデータに保存されている投稿者の名前 (反復可能)
-metadata.creator <name>
    エイリアス -creator
    SWF メタデータに保存されている作成者の名前 (反復可能)
-metadata.date <text>
    エイリアス -date
    SWF メタデータに保存されている作成日
-metadata.description <text>
    エイリアス -description
    SWF メタデータに保存されているデフォルトの説明
-metadata.language <code>
    エイリアス -language
    SWF メタデータに保存されている言語 (EN、FR など) (反復可能)
-metadata.localized-description <text> <lang>
    エイリアス -localized-description
    SWF メタデータに保存されているローカライズされた RDF/XMP の説明 (反復可能)
-metadata.localized-title <title> <lang>
    エイリアス -localized-title
    SWF メタデータに保存されているローカライズされた RDF/XMP タイトル (反復可能)
-metadata.publisher <name>
    エイリアス -publisher
    SWF メタデータに保存されている発行者の名前 (反復可能)
-metadata.title <text>
    エイリアス -title
    SWF メタデータに保存されているデフォルトのタイトル
-output <filename>
    エイリアス -o
    作成する SWF ムービーのファイル名
-package-description-file <string>
    パッケージの説明を含むファイル。
-packages.package <string> <string>
    エイリアス -package
    パッケージ名の説明を指定します。 (反復可能)
-runtime-shared-libraries [url] [...]
    エイリアス -rsl
    アプリケーションが起動する前にロードされるランタイム共有ライブラリの URL の一覧 (反復可能)
-runtime-shared-library-path [path-element] [rsl-url] [policy-file-url] [rsl-url] [policy-file-url]
    エイリアス -rslp
    リンクする SWC、読み込む RSL URL、ポリシーファイル URL (オプション) およびフェイルオーバー URL (オプション)
    を指定します  (反復可能)
-static-link-runtime-shared-libraries
    エイリアス -static-rsls
    ドメイン間の rsl によって指定されたライブラリを静的にリンクします。
-swf-version <int>
    コンパイル済 SWF ファイルのバージョンを指定します。
-target-player <version>
    アプリケーションがターゲットとするプレーヤーのバージョンを指定します。
    より新しいバージョンを必要とする機能は、アプリケーションにコンパイルされません。サポートされる最小の値は「9.0.0」です。
-templates-path <string>
    カスタムテンプレートのパス。
-tools-locale <string>
    エラーと警告を通知する際にコンパイラーで使用するロケールを指定します。
-use-direct-blit
    アクセラレーションを使用できる場合は、画面へのグラフィックの転送にハードウェアアクセラレーションを使用します。
-use-gpu
    アクセラレーションを使用できる場合は、グラフィックの描画時に GPU コンポジット機能を使用します。
-use-network
    ネットワークリソースへのアクセスについて SWF にフラグを設定するかどうかを切り替えます
-version
    プログラムのビルドバージョンを表示します
-warnings
    警告の表示を切り替えます
-window-title <string>
    ブラウザーウィンドウに表示するタイトル。

まとめ

　見ての通り、asdocには溢れんばかりの機能があるので、全然把握できてない。
　そして、asdoc出力用のコメントの書き方があるんだけど、今回は書かない、もうそんな余力ない。
　AdobeのASDocの資料をみれば、わかるよーなわからないよーな感じかと思う。Adobe Flex 4.6 * Documenting ActionScript elementsと、Adobe Flex 4.6 * ASDoc tagsあたり。

　Flash IDE側に、[クラスのドキュメントを生成...]みたいなメニュー付けてもバチは当たらん気がするんだけど、なぜそうしてないんだろうか。
　単にAdobe社内の連絡・連携が取れてないだけって気がするんだけどね。