ActionScript中的代码注释常用的ASDoc规范

转自：http://blog.csdn.net/monitor1394/article/details/7669213

       优美的注释是优美代码的重要组成部分。好的注释不仅可以让别人快速理解代码，部分语言还可以用注释生成对应的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>之间。

        以下是我写的用于演示且带有详细注释的测试代码。其中很多内容可能和类无关，只是想尽可能多地列出一些常用的注释规范：

[javascript] view
plaincopy

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文档为：