ASDoc入門

ASDocはActionScriptのクラス定義からその仕様書を自動でHTML文書化するツールで、Flex 2.0.1から正式に付属しています(SDKの中に入っています)。
Adobe Flex 2 Language Reference (Flex 2.0.1 jp, Flex 2.0.1)と同様の形式で出力されます。
mxmlについては、ブロックで定義されたActionScriptエンティティについてのみ出力される様です。

ASDoc dosen't eat Unicode. ASDocはUnicodeを食べない。

まぁAPI仕様書を作るのにこんなに便利なものは無いだろうということで試してみたのですが、mxmlcもfcshもcmd.exeから渡されるUnicodeを受け付けるので、ついついそのままデスクトップで試してみたりすると案の定駄目。

An unexpected error occurred.
Error #1500: Error occurred opening file C:\Documents and Settings\USERPROFILE\ﾂデﾂスﾂクﾂトﾂッﾂプ\sandbox\asdoc-output\toplevel.xml.

(エラーのロケーションは不明)XSLT エラー (javax.xml.transform.TransformerException): java.io.FileNotFoundException: C:\Documents and Settings\USERPROFILE\デスクトップ\sandbox\asdoc-output\toplevel_classes.xml (指定されたファイルが見つかりません。)

というエラーが出ます。文字化けの具合から推察するに、どうやらASDocはUnicodeしかわからない奴(cmd.exe)にUTF-8で話したいらしいです。私が何か適当なshellでも使えば済むんですけどね。
一応、前半の処理は行われているようで、asdoc-outputの中には、以下のファイルができています。
＃ ASDocが無い！と怒るtoplevel_classes.xmlもちゃんとある。ASDocは自分では作れても取りに行けてない。

index-list.html
index.tmp
mxml-tags.html
package-frame.html
title-bar.html
toplevel.xml

ASDocの実行

ということでpathに日本語が入ってないところで実行。

C:\sandbox>dir /b /s
C:\sandbox\foo
C:\sandbox\foo\alfa.as
C:\sandbox\foo\bravo.as
C:\sandbox\foo\charlie.as
C:\sandbox\foo\delta.as
C:\sandbox\foo\echo.as

こんな感じに用意しておいて、

C:\sandbox>asdoc -doc-sources .

はい完了。これでsandboxディレクトリ以下の全てのパッケージにある全てのクラスのドキュメントができました。簡単ですね。
作成された文書はasdoc-outputに出力されていますので、中にあるindex.htmlを開けば読むことができます。

使いそうなオプションはこういうところでしょうか。

 -source-path     //基準となるファイルパスを指定
 -doc-sources     //パッケージを指定
 -doc-classes     //クラスを指定
 -exclude-classes //除外するクラスを指定
 -output          //出力先
 -main-title
 -window-title
 -footer
 -package [name] [description]
 -templates-path
 -left-frameset-width
 -actionscript-file-encoding

基本はこんな感じで使うと思います。

// C:\hoge にある foo.bar パッケージ以下をドキュメント化
C:\>asdoc -source-path C:\hoge -doc-sources C:\hoge\foo\bar

// C:\hoge にある foo.bar パッケージの baz クラスをドキュメント化
C:\>asdoc -source-path C:\hoge -doc-classes foo.bar.baz
C:\>asdoc -source-path C:\hoge -doc-sources C:\hoge\foo\bar\baz.as

ASDocコメントの書き方

ASDocで出力される文書の詳細を書く為には、ActionScriptにASDocコメントの形式でコメントを書きます。ASDocコメントの中ではASDocタグやHTMLタグが利用できます。

本当に簡単な例。

/**
 * The foo class provides echo method.
 */
public class foo{
    /**
     * Outputs given message.
     * @param message Output text.
     */
    public function echo(message:String):void{
        trace(message);
    }
}

どのようなタグが利用できるかはASDoc_Tagsを参考に。

日本語の利用

ASDocコメントで日本語を利用するためには、.asや.mxmlをUTF-8にして保存しておけば問題なく日本語で出力されます。
ANCI(Shift-JIS)やEUC-JPの場合は、

 // -compiler.actionscript-file-encoding
 -actionscript-file-encoding Shift_JIS
 -actionscript-file-encoding EUC-JP

とオプションをつけておけば文字化けしません。
またBOMのお陰か間違ったオプションを指定してもUTF-8を誤読はしないようです。

-localeオプションはお好みで。

 // -compiler.locale
 -locale ja_JP

注意

-source-pathを指定しなかった場合に、ASDocはpackage宣言を元に文書化を行うようで、同クラス名で同パッケージの別ファイルがあったりすると内容が混ざるようです。warningも特に出ません。バックアップしたファイルなどが文書化するpathに含まれる場合などに注意が必要です。

参考

その他のオプションやASDocタグの詳細については、Flex2.0.1に含まれているということもあってLiveDocsに文書があります。

• ASDoc の使用 -- Flex 2.01

でも、ちょっと情報が少ない感じがします。

Adobe Labsのwikiのほうが充実していて参考になると思います。

• ASDoc:Using ASDoc - Adobe Labs
• ASDoc:Creating ASDoc Comments - Adobe Labs