クラス、プロパティ、メソッド、およびメタデータエレメントに ASDoc コメントを追加して、ActionScript クラスを文書化できます。MXML ファイルの文書化の詳細については、MXML ファイルの文書化を参照してください。

クラスの文書化

ASDoc ツールは、すべてのパブリッククラスをその出力に自動的に含めます。次の例に示すように、クラスの ASDoc コメントを class 宣言の直前に置きます。

/**
* The MyButton control is a commonly used rectangular button.
* MyButton controls look like they can be pressed.
* They can have a text label, an icon, or both on their face.
*/
public class MyButton extends UIComponent {
}

このコメントは、関連付けられたクラスの HTML ページの最上部に表示されます。

出力からクラスを省略するように ASDoc を設定するには、次の例に示すように、ASDoc コメントの任意の位置に @private タグを挿入します。

/**
* @private
* The MyHiddenButton control is for internal use only. 
*/
public class MyHiddenButton extends UIComponent {
}

プロパティの文書化

ASDoc ツールは、すべてのパブリックプロパティと保護されたプロパティをその出力に自動的に含めます。変数として定義されたプロパティや、setter/getter メソッドとして定義されたプロパティを文書化できます。

変数として定義されたプロパティの文書化

次の例に示すように、変数として定義されたパブリックプロパティまたは保護されたプロパティの ASDoc コメントを var 宣言の直前に置きます。

/**
*The default label for MyButton.
* 
*@default null 
*/
public var myButtonLabel:String;

プロパティのベストプラクティスでは、プロパティのデフォルト値を指定する @default タグを含めます。@default タグの形式は次のとおりです。

@default value 

このタグは、プロパティの出力に次のテキストを生成します。

The default value is value. 

デフォルト値を計算したプロパティ、または複雑な記述を持つプロパティでは、@default タグを省略し、デフォルト値をテキストで記述します。

ActionScript を使用すると、複数のプロパティを 1 つのステートメントで宣言できます。ただし、これでは、プロパティごとに一意の文書化ができません。そのようなステートメントに使用できる ASDoc コメントは 1 つだけで、このコメントは、そのステートメントのすべてのプロパティについてコピーされます。例えば、次のドキュメントコメントは、1 つの宣言として記述しても意味がなく、2 つの宣言として処理した方が有効に処理できます。

/** 
 * The horizontal and vertical distances of point (x,y)
 */
public var x, y;// Avoid this 

ASDoc は直前のコードから次のドキュメントを生成します。

public var x
    The horizontal and vertical distances of point (x,y)

public var y
    The horizontal and vertical distances of point (x,y)

getter/setter メソッドによって定義されたプロパティの文書化

setter/getter メソッドによって定義されたプロパティは、ASDoc ツールによって特別に処理されます。これは、これらのエレメントがメソッドではなくプロパティとして使用されるからです。したがって、ASDoc は、setter/getter メソッドによって定義されるアイテムについてプロパティ定義を作成します。

setter メソッドと getter メソッドを定義する場合は、1 つの ASDoc コメントを getter の前に挿入し、setter を @private とマークします。次の例に示すように、通常は ActionScript ファイルでは getter の方が前になるので、この方法をお勧めしています。

/**
* Indicates whether or not the text field is enabled.
*/
public function get html():Boolean {}; 

/**
* @private
*/
public function set html(value:Boolean):void {};

getter/setter メソッドによって定義されたプロパティを ASDoc が処理する方法は、次の規則によって定められます。

• setter/getter メソッドの前に ASDoc コメントを置くと、このコメントは出力に含まれます。
• setter メソッドと getter メソッドの両方を定義する場合は、setter の前か getter の前に 1 つの ASDoc コメントだけが必要です。
• setter メソッドと getter メソッドを定義する場合は、1 つの ASDoc コメントを getter の前に挿入し、setter を @private とマークします。
• setter メソッドと getter メソッドを特定の順序で定義する必要はありません。また、ソースコードファイル内で連続している必要もありません。
• getter メソッドだけを定義すると、プロパティは読み取り専用とマークされます。
• setter メソッドだけを定義すると、プロパティは書き込み専用とマークされます。
• パブリック setter メソッドとパブリック getter メソッドの両方をクラスで定義し、@private タグを使用して非表示にする場合は、両方のメソッドを @private でマークする必要があります。
• クラスに 1 つのパブリック setter または getter メソッドだけがあり、@private とマークされている場合は、ASDoc は通常の @private 規則を適用し、そのメソッドを出力から省略します。
• サブクラスは、常に表示されるスーパークラスの setter/getter メソッドの定義を継承します。

メソッドの文書化

ASDoc ツールは、すべてのパブリックメソッドと保護されたメソッドをその出力に自動的に含めます。次の例に示すように、パブリックメソッドまたは保護されたメソッドの ASDoc コメントを function 宣言の直前に置きます。

/**
* This is the typical format of a simple multiline documentation comment
* for the myMethod() method.
*
* <p>This is the second paragraph of the main description
* of the <code>myMethod</code> method.
* Notice that you do not use the paragraph tag in the
* first paragraph of the description.</p>
* 
* @param param1 Describe param1 here.
* @param param2 Describe param2 here.
* 
* @return A value of <code>true</code> means this; 
* <code>false</code> means that.
*
* @see someOtherMethod
*/
public function myMethod(param1:String, param2:Number):Boolean {}

メソッドが引数を取る場合は、各引数の @param タグを含めてその引数を記述します。ASDoc コメントでの @param タグの順序は、メソッドの引数の順序に合わせる必要があります。@param タグのシンタックスは次のとおりです。

@param paramName description 

paramName には、引数の名前を記述し、description には引数の説明を記述します。

メソッドが値を返す場合は、@return タグを使用して戻り値を記述します。@return タグのシンタックスは次のとおりです。

@return description 

ここで、description は戻り値の説明です。

メタデータの文書化

Flex は、メタデータタグを使用してコンポーネントのエレメントを定義します。ASDoc はこれらのメタデータタグを認識し、プロパティまたはメソッド定義と同様に処理します。ASDoc によって認識されるメタデータタグには次のようなものがあります。

• [Bindable]
• [DefaultProperty]
• [Effect]
• [Event]
• [Style]

これらのメタデータタグの詳細については、『Adobe Flex 3 コンポーネントの作成と拡張』のカスタムコンポーネントのメタデータタグを参照してください。

バインド可能プロパティの文書化

バインド可能プロパティは、データバインディング式のソースとして使用できるプロパティです。プロパティをバインド可能とマークするには、[Bindable] メタデータタグをプロパティ定義の前またはクラス定義の前に挿入し、クラス内部の定義されたすべてのプロパティをバインド可能にします。

プロパティがバインド可能として定義されている場合は、ASDoc は、プロパティの出力に次の行を自動的に追加します。

This property can be used as the source for data binding.

[Bindable] メタデータタグの詳細については、『Adobe Flex 3 コンポーネントの作成と拡張』のカスタムコンポーネントのメタデータタグを参照してください。

デフォルトのプロパティの文書化

[DefaultProperty] メタデータタグは、MXML ファイル内でコンポーネントを使用するときにコンポーネントのデフォルトプロパティの名前を定義します。

ASDoc が [DefaultProperty] メタデータタグを検出すると、デフォルトのプロパティを指定するクラスの説明に行を自動的に追加します。例については、『Adobe Flex リファレンスガイド』の List コントロールを参照してください。

[DefaultProperty] メタデータタグの詳細については、『Adobe Flex 3 コンポーネントの作成と拡張』のカスタムコンポーネントのメタデータタグを参照してください。

エフェクト、イベント、およびスタイルの文書化

メタデータタグを使用して、エフェクト、イベント、およびスタイルに関する情報をクラス定義に追加します。通常は、[Effect]、[Event]、および [Style] メタデータタグは、クラス定義ファイルの先頭に表示されます。メタデータタグを文書化するには、次の例に示すように、メタデータタグの前に ASDoc コメントを挿入します。

/**
* Defines the name style.
*/
[Style "name"]

イベントとエフェクトでは、そのイベントまたはエフェクトに関連付けられたイベントクラスの名前がメタデータタグに含まれます。次の例に、Flex mx.controls.Button クラスのイベント定義を示します。

/**
* Dispatched when the user presses the Button control.
* If the <code>autoRepeat</code> property is <code>true</code>,
* this event is dispatched repeatedly as long as the button stays down.
*
* @eventType mx.events.FlexEvent.BUTTON_DOWN
*/
[Event(name="buttonDown", type="mx.events.FlexEvent")]

mx.events.FlexEvent.BUTTON_DOWN 定数の ASDoc コメントで、Event クラスの bubbles、cancelable、target、および currentTarget プロパティと、Event のサブクラスによって追加されたその他のプロパティの値を定義するテーブルを挿入します。次の例に示すように、ASDoc コメントの最後に @eventType タグを挿入し、ASDoc がそのコメントを検出できるようにします。

/**
* The FlexEvent.BUTTON_DOWN constant defines the value of the 
* <code>type</code> property of the event object 
* for a <code>buttonDown</code> event.
*
* <p>The properties of the event object have the following values:</p>
* <table class=innertable>
* <tr><th>Property</th><th>Value</th></tr>
* ...
* </table>
*
* @eventType buttonDown
*/
 public static const BUTTON_DOWN:String = "buttonDown"

ASDoc ツールは、このイベントについて次のようないくつかの操作を行います。

• mx.controls.Button クラスの出力で、ASDoc は [Event] メタデータタグの type 引数によって指定されるイベントクラスへのリンクを作成します。
• ASDoc は、mx.events.FlexEvent.BUTTON_DOWN 定数の説明を、Button クラスの buttonDown イベントの説明にコピーします。

詳しい例については、mx.controls.Button クラスと mx.events.FlexEvent クラスを参照してください。

[Effect]、[Event]、および [Style] メタデータタグの詳細については、『Adobe Flex 3 コンポーネントの作成と拡張』のカスタムコンポーネントのメタデータタグを参照してください。