ASDoc コメントの作成 -- Flex 2.01

標準のプログラミング方法では、コメントをソースコードに含めます。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 2 リファレンスガイドに表示される 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 つのコメントだけを認識します。

一般的な間違いとして、クラスの ASDo コメントと 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 コードを使用して入力する必要があります。たとえば、小なり (<) または大なり (>) 記号をコメントで使用するには、< と > を使用します。コメントでアットマーク (@) を使用するには、&64; を使用します。このようなコードを使用しないと、これらの文字は出力でリテラル HTML 文字と解釈されます。

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

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

/**
*  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 ファイルを処理する方法を次の規則にまとめます。