ASDoc の書き方講座

仕事用に作ったまとめをそのまま転載。


■参考リンク
以下のリンクを見ておけば一通り大丈夫です。
ASDoc コメントの作成
ASDoc タグ一覧
@see タグや@copy タグの使用方法
びんた先生(beinteractive)のパーフェクトASDocタグ講座


■Flex 3 SDKのasdocコマンドを使ってみる
asdoc -helpを見れば良いのですが、helpが見づらくてややっこしいので、まとめてみました。
http://livedocs.adobe.com/flex/3/html/help.html?content=asdoc_9.html#142061
以下のコマンドを入力すればOKです。ここで、$FLEX_HOMEは Flex SDKをインストールしたパスです。

asdoc -compiler.source-path=自分が追加したいソースパス, -compiler.library-path=$FLEX_HOME/frameworks/libs,自分が追加したいライブラリパス -doc-sources=ドキュメントに出力したいソースのパス

$FLEX_HOME/frameworks/libsをライブラリパスに含めないとビルドが通らないのがくせ者です。JavaDocはtools.jarを自動的にパスに含めてくれるんだから、ASDocだって自動的にやってくれと言う気がします＞＜ ちなみに、Flex Builderとか使えばこんな面倒な事をしなくても簡単にASDocを出力することができるみたいです。


■気をつけるところ
ASDocの最初の一文は必ずピリオドで終了する
腹立たしいですがピリオド{{.}}が最初の一文の区切りになっているようなので、句読点{{。}}ではなくピリオドを使いましょう。 たとえば、

package {
/**
 * ASDocのテスト用のクラスです.
 * 
 * 第一文は必ずピリオドで終了する必要があります。
 * 試しに上記のピリオドを句読点に変更してドキュメントを出力すると違いが分かると思います。
 */
 public class ASDocTestClass {}
 }

のように書く必要があります。こうしないと、ドキュメントを生成したときに説明文が長ったらしくなって困ります。