ASDocの書き方について

ASDocの書き方の癖が強かったので、ASDocの基本的な書き方をまとめておく。

ASDocの書き方

注意点

ASDocの最初の一文は必ずピリオドで終了すること。ASDocでは、ピリオド(.)が最初の一文の区切りになっているので、句読点(。)ではなくピリオドを使う。

package {
    /**
     * ASDocのテスト用のクラスです.
     * @author SmokyDog
     * @internal (C) ぷろじぇくとM 2013/12/12
     */
    public class ASDocTestClass {}
}

ASDoc内では、コメントを記入する際にクラスやメソッドの役割を示すためにタグを使用する。使用できるタグには以下の種類がある。

タグ 説明
@default value デフォルト値を指定、「デフォルト値は value です」と出力
@eventType package.class.CONSTANT Eventメタデータの出力
@example exampleText コード例、コードは タグで囲む
@internal text 内部コメント用、ドキュメントには出力されない
@param paramName description メソッドパラメータの説明
@private 出力しない、クラスのasdocに入れるとクラス全体が出力されなくなる
@return description 戻り値の説明
@see reference [displayText] 参照の生成
@throws package.class.className description 例外の説明

まとめ

最低限、@paramタグと@returnタグと@throwsタグは覚えたい。@internalタグも適宜記述する。また、JavaDocに存在する@authorタグはASDocには存在しないが、大規模開発ではソースの著者が分かりにくくなりがちなので著者名は記述した方が良い。

参考
A-Liaison BLOG: ASDoc の書き方講座
ActionScript3.0 asdoc作成 – kozy.heteml.jp