優美的註釋是優美代碼的重要組成部分。好的註釋不僅可以讓別人快速理解代碼，部分語言還可以用註釋生成對應的html文檔，在不看源碼的情況下快速瞭解框架，或後期的具體查詢。熟悉Java 的程序猿都知道Javadoc，不知用ActionScript的程序猿都知道asdoc不？asdoc和Javadoc類似，是adobe官方提供的ActionScript的API文檔生成工具。要想能成功生成API文檔，代碼的註釋需要滿足一定的規範。
結合例子，列舉一下我常用的規範：
- 用於生成API文檔的註釋必須用（/** */）註釋格式，註釋內帶<xx>的必須爲html標籤，且要有</xx>與之匹配。 常用的html標籤有：
- <p></p>：段落
- <i></i>：斜體
- <b></b>：粗體
- <ul></ul>：無序列表
- <ol></ol>：有序列表
- <li></li>：列表項，有序列表和無序列表中都使用 <li> 標籤
- <code></code>：源程序代碼
- 在類的上方寫關於該類的介紹以及注意事項或使用例子等註釋。若類帶[Bindable] 和[SWF]等標籤，則註釋必須寫於類聲明的上一行。
- 類必須用@author 寫明作者和代碼編寫時間，方便其他開發人員及時與原作者溝通。
- 與該類相關的其他類用@see 標明，方便查閱者快速瞭解此類。
- 聲明爲public的變量必須寫用（/** */）寫清楚註釋。
- 類的構造方法要寫清楚構造什麼對象，參數和異常。
- 類的get或set方法可只對get方法進行註釋，且不用@return。
- 類的其他public方法要註釋好該方法的功能、參數、參考方法和返回值等。
- 類方法中寫例子時用@example標籤，且代碼直接粘貼在<listing version="3.0">和</listing>之間。
以下是我寫的用於演示且帶有詳細註釋的測試代碼。其中很多內容可能和類無關，只是想儘可能多地列出一些常用的註釋規範：
package test {
import flash.utils.getTimer;
[SWF(backgroundColor="#000000", frameRate="50", width="1000", height="600")]
/**
* 性能測試
* <p>
* <code>Test</code>類用於測試<code>Vector</code>類和<code>Array</code>類的<i>性能</i>。
* 一般而言，<code>Vector</code>類的讀寫訪問速度比<code>Array</code>類，
* 若爲<code>Vector</code>分配特定長度並將其長度設爲固定值，可進一步提高<i>性能</i>。
* </p>
* <p>
* 當前用以下方案進行測試：
* <ol>
* <li>初始化指定大小的<code>Array</code>數組需要的時間</li>
* <li>初始化指定大小的<code>Vector</code>數組需要的時間，<code>Vector</code>使用默認值</li>
* <li>初始化指定大小的<code>Vector</code>數組需要的時間，<code>Vector</code>分配長度並設爲固定值</li>
* <li><code>Array</code>數組查詢某個值需要的時間</li>
* <li><code>Vector</code>數組查詢某個值需要的時間</li>
* </ol>
* </p>
* <p>
* 下面代碼演示如何使用<code>Test</code>類進行測試：
* <listing version="3.0">
var test1:Test=new Test("Vector默認大小",10000000,false);
var test2:Test=new Test("Vector預分配大小",10000000,true);
test1.start();
test2.start();
</listing>
* </p>
* <p><b>注：</b>儘可能使用<code>Vector</code>對象的API，因爲他們的運算速度可能更快。</p>
*
* @see Vector
* @see Array
*
* @since ActionScript 3.0
*
* @author monitor
* Created on 2012-6-16,下午2:20:38
*/
public class Test {
/** 數組默認大小 */
public static const SIZE:int=10000;
private var _name:String;
private var _size:int;
private var _flag:Boolean;
/**
* 構造一個指定名稱和容量並指示<code>Vector</code>是否指定固定長度的<code>Test</code>
* @param name 名稱
* @param size 數組容量大小，最大值爲10000000
* @param flag <code>Vector</code>是否指定固定長度
* @throws ArgumentError 分配的數組大於10000000
*/
public function Test(name:String,size:int,flag:Boolean){
if(size>1000000){
throw new ArgumentError("分配大小過大");
}
_name=name;
_size=size;
_flag=flag;
}
/**
* 開始測試並輸出測試結果
* @example
* 下面代碼演示如何使用<code>Test</code>類進行測試：
* <listing version="3.0">
var test1:Test=new Test("Vector默認大小",10000000,false);
var test2:Test=new Test("Vector預分配大小",10000000,true);
test1.start();
test2.start();
</listing>
*
* @see #getSize()
* @see Array#indexOf()
*/
public function start():void{
var start:Number;
var time1:Number,time2:Number,time3:Number,time4:Number;
var i:int=0;
start=getTimer();
var array:Array=new Array();
for(i=0;i<_size;i++){
array[i]=i;
}
time1=getTimer()-start;
start=getTimer();
var vector:Vector.<Number>;
if(_flag){
vector=new Vector.<Number>(_size,true);
}else{
vector=new Vector.<Number>();
}
for(i=0;i<_size;i++){
vector[i]=i;
}
time2=getTimer()-start;
var find:int=_size/2;
start=getTimer();
array.indexOf(find);
time3=getTimer()-start;
start=getTimer();
vector.indexOf(find);
time4=getTimer()-start;
trace("Vector和Array性能測試："+_name);
trace("初始化大小爲 "+_size+" 的Array 花費："+time1+" ms");
trace("初始化大小爲 "+_size+" 的Vector花費："+time2+" ms");
trace("Vector 比 Array 快："+(time1-time2)+" ms");
trace("查找 "+find+" ，Array 花費："+time3+" ms");
trace("查找 "+find+" ，Vector花費："+time4+" ms");
}
/**
* 名稱
*/
public function get name():String{
return _name;
}
public function set name(name:String):void{
_name=name;
}
/**
* 獲得數組大小
* @return 數組大小
*/
public function getSize():int{
return _size;
}
/**
* 獲得<code>Vector</code>是否使用固定值的標識
* @reutrn 使用固定值返回<code>true</code>，否則返回<code>false</code>
*/
public function getFlag():Boolean{
return _flag;
}
}
}
示例1：
對應的API文檔如下：
示例2：
對應的API文檔爲：
示例3：
對應的API文檔爲：
:示例4：
對應的API文檔爲：
示例5：
對應的API文檔爲：
示例6：
對應的API文檔爲：
