为你的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文档。
更详细的asdoc命令使用可以查看这里：http://livedocs.adobe.com/flex/3 ... ontent=asdoc_9.html
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文档中。

更多的asdoc标记请参看：http://livedocs.adobe.com/flex/3 ... asdoc_6.html#186140