為你的ActionScript項目建立API文檔

作為一個developer，寫項目的API文檔是非常重要的一件事情，flash developer也不例外。ASDoc能讓我們快速建立ActionScript項目的API文檔。

下面以一個實際的示例來說明如何建立API文檔：

1)打開Adobe Flex 3 SDK Command Prompt。

2)用cd指令進入ActionScript項目的目錄，如：cd D:\flashlizi\asdoc。

3)輸入ASDoc指令：

asdoc -source-path . -window-title "ASDoc示範示例類" -package riaidea.asdoc "A Example of Using ASDoc" -doc-classes riaidea.utils.zip.ASDocExample

這是一個基本的asdoc指令。其中參數source-path表示as源檔案目錄，如果在當面目錄則用點“.”來表示。window-title表示幫助文檔的視窗标題，即浏覽器視窗标題。package參數用來描述一個包，如這裡描述包riaidea.asdoc為"A Example of Using ASDoc”。doc-classes用來指明需要生成API文檔的類，如果指定的類中還引用了其他自定義類，那這些類也會生成API文檔。

4)執行完畢後，在asdoc目錄下會生成了一個asdoc-output目錄，裡面就是API文檔。一般的，我們生成的API文檔無需按26個字母分類，是以我們可以把裡面的all-index-A.html到all-index-Z.html删除，并删除title-bar.html中的Index連結，這樣的API文檔就精簡多了。

下面是本例中的類riaidea.utils.zip.ASDocExample的源碼：

package riaidea.asdoc{   

    import flash.display.Sprite;   

    import flash.events.Event;   

    /**  

    * 當建立一個ASDocExample執行個體的時候排程init事件。  

    * @eventType mx.events.FlexEvent.BUTTON_DOWN  

    */  

    [Event(name="init", type="flash.events.Event")]   

     * ASDoc示範類。此例示範了如何寫注釋才能建立一個基本的AS項目的API文檔。  

     * @example  

     * <listing version="3.0">  

     * var eg:ASDocExample=new ASDocExample();  

     * eg.print("ASDoc示範類");  

     * eg.test("flashlizi");  

     * </listing>  

     * @see http://www.riaidea.com  

     */  

    public class ASDocExample extends Sprite {   

        /**  

         * 執行個體的建立者。  

         * @default flashlizi  

         */  

        public var creator:String;   

        private var _date:Date;   

         * 構造函數-constructor。  

        public function ASDocExample() {   

            this.creator = "flashlizi";   

            this._date = new Date();   

            dispatchEvent(new Event(Event.INIT));   

        }   

         *    列印參數指定内容。  

         * @param    content 要列印的内容。  

        public function print(content:String):void {   

            trace(content);   

         * 測試類的建立者是否與參數指定名稱相同。  

         * @param    name 測試指定的名稱。  

         * @return    建立者與指定名稱相同傳回true，否則傳回false。  

        public function test(name:String):Boolean {   

            return name == creator;   

         * 執行個體的建立時間。  

        public function get date():Date {   

            return date || new Date();   

        public function set date(value:Date):void {   

            _date = value;   

    }   

} 

現在來說明一下如果寫類的注釋才能建立一個比較完善的API文檔。

1）首先，隻有包含在/**與*/之間的注釋才能被asdoc識别。對一個類的方法或者屬性做注釋，隻要在之前加上這樣的注釋就可以了。

2）注釋的第一行開始（不包括注釋标記）是被注釋對象（方法、屬性等）的說明介紹。當出現@param 這樣的注釋标記的時候，asdoc就會自動解析為相應的内容。

3）本例ASDocExample中包含了一些常用的asdoc标記：

a、eventType。隻能用于注釋Event元标記，如[Event(name="init", type="flash.events.Event")]。這樣在API文檔中這個事件會出現這個類的Event說明塊中。

b、example。用于建立一個示例。示例代碼需寫在< listing >和< /listing >之間。

c、see。用于建立“另請參見”說明塊。

d、default。用于建立屬性的“預設值”說明。

e、param。用于建立對方法的參數的說明。

f、return。用于建立對方法的傳回值的說明。

g、private。使用此标記的方法或屬性将不會輸出到API文檔中。

    本文轉自 OldHawk  部落格園部落格，原文連結：http://www.cnblogs.com/taobataoma/archive/2008/04/22/1165252.html，如需轉載請自行聯系原作者