Adobe LabsにてAS3用ドキュメンテーションツール「ASDoc」が公開されています。これは、クラスやメソッドに対して書かれたJavaDoc形式のコメントをHTML化してくれるものです。

というわけで、早速AS3Unitで試してみました。

うーん、正直、あまり品質は高くないような気がします。assertByteArrayEquals.as内に書いたプライベートFunctionがドキュメント化されちゃってるし・・・。コメント書いてないヤツはParametersの改行がおかしいし。何より、コマンドラインでやるのはキツイ。あとハマったのが、-doc-sources（ここで指定したフォルダ内全てドキュメント化するオプション）を指定する場合でも、-source-pathはきちんと書いてあげないといけない。というか、Flex2のlangrefは何で生成してるんだろう？まさかコレじゃないよなぁ。

まあ、それはともかく、今後ASDocがスタンダードになるのは必至なので、今の内にASDocオンリーのタグを覚えておきましょう。（ちなみに、実際にASDocにかけないで書いてるので間違いがあればご指摘願います）

@copy - ドキュメントをコピー

指定したクラスやメソッドに対するドキュメントを、そのままコピーします。

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

というクラスがあったとして、

public class B
{
    /**
     * @copy A#echo
     */
    public function output(message:String):void
    {
         trace(message);
    }
}

と記述すれば、クラスBのoutputメソッドに対しても、クラスAのechoメソッドと全く同じドキュメント（概要, @param, @return）が付きます。

@default - デフォルト値の明示

プロパティに対するデフォルト値を記述できます。

public class P
{
    private var _x:int = 20;

    /**
     * @default 20
     */
    public function get x():int
    {
       return _x;
    }
    public function set x(value:int):void
    {
       _x = value;
    }
}

@eventType - 関連するイベントの指定

メソッドを呼び出したときに送出されるイベントなどが指定できます。文字列又はイベント定数で指定します。

public class E extends EventDispatcher
{
    /**
     * @eventType Event.INIT
     */
    public function initialize():void
    {
        dispatchEvent(new Event(Event.INIT));
    }
}

@example - 例を記述

クラスやメソッドの使い方の例を記述できます。コードは<listing version="3.0">～</listing>で囲むようです。

public class Ex
{
    /**
     * @example The following code shows this function usage:
     * <listing version="3.0">
     * new Ex().echo('message'); // Outpus: message
     * </listing>
     */
    public functon echo(message:String):void
    {
        trace(message);
    }
}

@includeExample - 外部asファイルを例として使用

外部asファイルのパスを指定すると、その内容を@exampleと同じように例として表示してくれます。更に、それをコンパイルしたswfまで同時に表示してくれます。swfが必要ない場合は最後に -noswf を付けます。

Example.as:

package
{
    import flash.display.Sprite;

    public class Example extends Sprite
    {
        public function Example()
        {
            addChild(new RectShape());
        }
    }
}

RectShape.as:

package
{
    import flash.display.Shape;

    /**
     * @includeExample Example.as
     */
    public class RectShape extends Shape
    {
        public function RectShape()
        {
            graphics.drawRect(0, 0, 20, 20);
        }
    }
}

ちなみに、コードに対して説明を加える時は、外部asファイルに @exampleText タグを用いて記述します。

...
    /**
     * @exampleText The following code shows this class usage:
     */
    public class Example extends Sprite
...

@inheritDoc - ドキュメントを継承

オーバーライドしたメソッドや、インターフェイスから実装したメソッド等に対してこのタグを指定すると、元のメソッドのドキュメントを@copyと同じように継承します。

public class A
{
    /**
     * Returns the class name.
     */
    public function getClassName():String
    {
        return 'A';
    }
}
public class B extends A
{
    /**
     * @inheritDoc
     */
    override public function getClassName():String
    {
        return 'B';
    }
}

B.getClassNameにも「Returns the class name」というドキュメントが引き継がれます。

@private - メンバを隠蔽

このタグが付けられたクラスやメソッドは、「完全に」ドキュメント化されなくなります（無いものとして扱われます）。