標準のプログラミング方法では、コメントをソースコードに含めます。ASDoc ツールは、ソースコード内の特定のタイプのコメントを認識し、そのコメントを生成される出力にコピーします。ASDoc ツールは、コメントの形式と解析に対する次の規則を認識します。

ASDoc コメントの記述

ASDoc コメントは、ASDoc コメントの先頭を表す文字 /** と、コメントの終わりを表す文字 */ の間にあるテキストで構成されます。コメント内のテキストは複数の行に続けることができます。

ASDoc コメントには次の形式を使用します。

/** 
* Main comment text.
* 
* @tag Tag text.
*/

ベストプラクティスとして、ASDoc コメントの各行の前にアスタリスク（*）文字を付け、その後に 1 つの空白を挿入することにより、ActionScript または MXML ファイルでコメントを読みやすくし、コメントを正しく解析できるようにします。ASDoc ツールがコメントを解析すると、各行の先頭のアスタリスクと空白文字が破棄され、最初のアスタリスクの前の空白とタブも破棄されます。

前の例の ASDoc コメントでは、出力に 1 段落の説明が作成されます。さらにコメント段落を追加するには、以降の各段落を HTML 段落タグ、<p></p> で囲みます。次の例に示すように、XHTML の標準に従って <p> タグを閉じる必要があります。

/**
* First paragraph of a multiparagraph description.
*
* <p>Second paragraph of the description.</p>
*/

Flex に付属のすべてのクラスには、『Adobe Flex リファレンスガイド』に表示される ASDoc コメントが含まれます。例えば、ASDoc コメントの例で mx.controls.Button クラスを表示します。

ASDoc コメントの配置

次の例で myMethod() メソッドについて示すように、クラス、インターフェイス、コンストラクタ、メソッド、プロパティ、またはメタデータタグの宣言の直前に、文書化する ASDoc コメントを配置します。

/**
* This is the typical format of a simple
* multiline (single paragraph) main description 
* for the myMethod() method, which is declared in 
* the ActionScript code below.
* Notice the leading asterisks and single white space
* following each asterisk.
*/
public function myMethod(param1:String, param2:Number):Boolean {}

ASDoc ツールは、メソッド本体に配置されたコメントを無視し、ActionScript ステートメント 1 つあたり 1 つのコメントだけを認識します。

よくある間違いに、クラスの ASDoc コメントと class 宣言の間に import ステートメントを配置することがあります。ASDoc コメントは、ファイル内のそのコメントの後の次の ActionScript ステートメントと関連付けられているので、この例では、class 宣言ではなく、import ステートメントとコメントが関連付けられます。

/**
* This is the class comment for the class MyClass.
*/
import flash.display.*; // MISTAKE - Do not to put import statement here.
class MyClass {
}

ASDoc コメントの形式設定

ASDoc コメントのメインの本体は、先頭の文字、/** の直後から始まり、次の例に示すようにタグセクションまで続きます。

/** 
* Main comment text continues until the first @ tag.
* 
* @tag Tag text.
*/

ASDoc コメントのメインの記述の最初の文には、宣言されたエンティティの簡潔で完全な記述が含まれていなければなりません。最初の文は最初のピリオドで終わります。この後に、スペース、タブ、または行終端子が続きます。

ASDoc は最初の文を使用して、そのクラスの HTML ページの先頭にある一覧表に値を入力します。各タイプのクラスエレメント（メソッド、プロパティ、イベント、エフェクト、スタイル）には、ASDoc 出力に個別の一覧表があります。

タグセクションはコメントの最初の ASDoc タグ（行を開始する最初の @ 文字で定義される）で始まり、先頭のアスタリスクや空白、先頭の区切り文字 /** は無視されます。メインの記述は、タグセクションの開始後は継続できません。

ASDoc タグの後のテキストは複数の行に続けることができます。任意の数のタグを使用できます。@param タグや @see タグのように一部のタグは繰り返すことができますが、その他のタグは繰り返しができません。

次の例は、メインの記述とタグセクションが含まれる ASDoc コメントを示しています。空白と先頭のアスタリスクを使用して、コメントを読みやすくしていることに注意してください。

/**
* Typical format of a simple multiline comment.
* This text describes the myMethod() method, which is declared below.
*
* @param param1 Describe param1 here.
* @param param2 Describe param2 here.
*
* @return Describe return value here.
*
* @see someOtherMethod
*/
public function myMethod(param1:String, param2:Number):Boolean {}

ASDoc タグの一覧については、ASDoc タグを参照してください。

@private タグの使用

ASDoc コメントを省略した場合でも、ASDoc ツールは、デフォルトで ActionScript クラスのすべてのパブリックエレメントと保護されたエレメントの出力を生成します。ASDoc にエレメントを無視させるには、@private タグが含まれる ASDoc コメントをコメントのいずれかの位置に挿入します。ASDoc コメントには、@private タグと共に追加のテキストを含めることができます。このタグも出力から除外されます。

ASDoc は、入力クラスのリストに含まれるすべてのパブリッククラスの出力も生成します。@private タグが含まれる ASDoc コメントをクラス定義の前に挿入することにより、クラス全体を無視することを指定できます。ASDoc コメントには、@private タグと共に追加のテキストを含めることができます。このタグも出力から除外されます。

継承したエレメントの除外

デフォルトでは、ASDoc ツールは、スーパークラスからサブクラスが継承したすべての ActionScript エレメントの情報とリンクをコピーします。場合によっては、継承したエレメントをサブクラスがサポートできないこともあります。[Exclude] メタデータタグを使用して、継承したエレメントを、継承したエレメントのリストから省略するように ASDoc に指示できます。

[Exclude] メタデータタグのシンタックスは次のとおりです。

[Exclude(name="elementName", kind="property|method|event|style|effect")] 

例えば、Button クラスの MyButton サブクラスで click イベントのドキュメントを除外するには、次の [Exclude] メタデータタグを MyButton.as ファイルに挿入します。

[Exclude(name="click", kind="event")] 

HTML タグの使用

ASDoc コメントのテキストは XHTML 互換の HTML で記述する必要があります。選択した HTML エンティティと HTML タグを使用して、段落を定義し、テキストの書式を設定し、リストを作成し、アンカーを追加できます。サポートされている HTML タグのリストについては、一般に使用される HTML エレメントの一覧を参照してください。

次の例のコメントには、出力の書式を設定するための HTML タグが含まれます。

/**
* This is the typical format of a simple multiline 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 {}

特殊文字の使用

シングルクォーテーションマークやダブルクォーテーションマークなどの UTF-8 以外の文字がソースファイルに含まれる場合は、ASDoc ツールが失敗することがあります。失敗すると、このツールにより表示されるエラーメッセージは、そのクラスについて作成された XML ファイルの一時 XML ファイルの行番号を参照しています。この情報は、特殊文字の場所を追跡する際に役立ちます。

ASDoc は、コメント内のすべての HTML タグとタグエンティティを出力に渡します。したがって、特殊文字をコメントで使用する場合は、相当する HTML コードを使用して入力する必要があります。例えば、小なり（<）または大なり（>）記号をコメントで使用するには、&lt; と &gt; を使用します。コメントでアットマーク（@）を使用するには、&64; を使用します。このようなコードを使用しないと、これらの文字は出力でリテラル HTML 文字と解釈されます。

一般的な HTML タグとその実体参照については、一般に使用される HTML エレメントの一覧を参照してください。

アスタリスク（*）はコメントを区切るために使用するので、ASDoc はコメント内部のアスタリスクはサポートしていません。ASDoc コメントでアスタリスクを使用するには、ダブルチルダ（~~）を使用する必要があります。

ASDoc コメントのテキストを非表示にする

ASDoc スタイルシートには hide と呼ばれるクラスが含まれており、このクラスを使用すると、クラス属性を hide に設定することにより、ASDoc コメントのテキストを非表示にできます。非表示のテキストは、ASDoc HTML 出力には表示されませんが、生成された HTML ファイルには表示されるので、機密情報には非表示のテキストを使用しないでください。次の例では、hide クラスを使用します。

/**
*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.
*
*<span class="hide">This text is hidden.</span>
*@eventType mx.events.FlexEvent.BUTTON_DOWN
*/

ASDoc コメントの解析規則

ASDoc が ActionScript ファイルを処理する方法を次の規則にまとめます。

• ASDoc コメントが ActionScript エレメントよりも前にある場合は、ASDoc はそのコメントとコードエレメントを出力ファイルにコピーします。
• ASDoc コメントが ActionScript エレメントよりも後にある場合は、ASDoc は、コードエレメントを空の説明とともに出力ファイルにコピーします。
• ASDoc コメントに @private ASDoc タグが含まれる場合は、関連付けられた ActionScript エレメントと ASDoc コメントは無視されます。
• コメントテキストは常に @ タグの前になければなりません。後ろにある場合は、コメントテキストは @ タグの引数として解釈されます。唯一の例外は @private タグです。このタグは、ASDoc コメントのどの場所に置くこともできます。
• ASDoc コメント内の <p></p> や <ul></ul> などの HTML タグは出力に渡されます。
• HTML タグは XML スタイルの表記規則を使用する必要があるため、必ず、開始タグと終了タグを指定してください。例えば、<li> タグは常に </li> タグで閉じる必要があります。