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には存在しないが、大規模開発ではソースの著者が分かりにくくなりがちなので著者名は記述した方が良い。