Flex帮助文档ASDoc

首先，我们一般会对类文件的类和成员以及成员函数做一些解析性说明。那么这个解析性说明应该怎么写呢？如果想给指定的类、成员属性、成员函数加上注释，可以在这些声明的顶部按照下面的格式属性注释：

　　（在flash builder里，按Ctrl+Shift+D可以很方便地添加AsDoc注释）　

　　（注意注释的文字和*之间必须有空格，不然第一个位置的任何文字会被忽视）

　　（注意我的ASDoc是通过公司的包汉化了的，有想要的可以留言）

　　源代码：

        /**
         * 公有字段
         */
        public var public_variable:Boolean;

　　效果：

　　

　　这样我们在进行一次文档生成操作后，会发现你所添加的注释会在响应的类、属性或者方法下面多出一行说明文字。关于注释的内容可以为任意字符，甚至可以搭配HTML标记来修饰注释内容。（其输出的是HTML当然可以用HTML标记来描述了，呵呵），说完最常用的注释后，接下来说一下被ASDoc所能解析的标记，下面将逐一进行探讨。

　　1、@author 用户名

　　此标记用于标记类的创始人，使用快捷键生成系统胡默认把用户名设定为你的计算机的用户名(如：administor)，网上某资料说可以通过如下三步修改：

　　Step1：打开C:\Program Files\Adobe\Adobe Flash Builder 4\‍FlashBuilder.ini。

　　Step2：在后面加入一行：-Duser.name=heguang。

　　Step3：注意要加在任何-vmargs语句后面，且等号没有空格。

　　但是我试了却没有用，反而弄的我的flash builder的空间需要修改，出错了。有知道的朋友请告诉我一声哦！

　　源代码：

/**
     * 实例类
     * @author liuyayun
     */
    public class Demo extends EventDispatcher

　　效果：

　　

　　实例类可以显示出来，下面的标记不能显示，估计也就是用来标记一下的吧！

　　2、@param标记

　　@param标记是为带参数的函数中的参数作注释用的标记。通过此标记可以生成对应的参数的说明。此标记的书写格式如下：

　　　　@param 参数名称 参数说明

　　从书写格式可以看出来，一个这样的标记仅对应一个方法中的一个参数。如果一个方法中包含多个参数可以用多个@param来进行说明。如下是一个例子：

　　源代码：

        /**
         * 方法的说明
         * @param name 第一个参数说明
         * @param age 第二个参数说明
         */
        public function public_method(name:String,age:Number):void
        {
        }

　　效果：

　　

　　从例子中可以看出来，在@param标记中写入的内容会被写入Parameters栏中。在官方文档中对@param标记的功能还提到了一点就是，写入的参数名称必须要对应方法签名中的参数名称。也就是说如果有两个参数，必须要按照定义的参数顺序来进行注释。追梦做了一个尝试，就是给一个带两个参数的方法注释时不按照签名定义来进行注释，发现注释变得混乱。同时，也尝试过把@param的paramName部分随便填上一些字符，但是输出的参数名称依旧会按照方法中的参数名称来显示。所以，可以得出一个结论就是paramName可以为任意名称，但注释信息必须要对应签名顺序中的参数，这样ASDoc也能为你把参数名称正确地分配到正确的注释中。

当然，笔者不赞成乱写参数名称的办法，因为这样会养成不好的习惯，同时也会造成程序的可读性降低。所以，应该对应参数名称来写入参数注释。

　　3、@example标记

　　@example是可以为某个类、方法或者属性加一个说明性的例子，从而让自己的代码更加容易理解。其书写格式为：

　　　　@example 例子的说明性文字

　　　　<listing version=”3.0”>

　　　　例子的代码

　　　　</listing>

　　从格式中可知，例子的代码是写在<listing />标记之中的（version=”3.0”可有可无，只是版本号），下面通过一个例子来说明一下，还是以public_method函数为例：

　　源代码：

/**
         * 方法的说明
         * @param name 第一个参数说明
         * @param age 第二个参数说明
         * @example 例子说明
         * <listing>
         * //初始化一个Demo对象
         * var demo:Demo=new Demo("追梦");
         * //调用方法public_method
         * demo.public_method("追梦的远远",22);
         * ...
         * </listing>
         */
        public function public_method(name:String,age:Number):void
        {
        }

　　效果：

　　

　　从上图可见，在@example后面的文字输出在Example的下面，此文字是用来对例子的一个说明。然后写在<listing />标记中的代码就放在一个灰色的矩形框中。根据官方的帮助说明，在个框是带水平滚动条的，所以当内容超出一定长度后就会显示水平的滚动条。追梦对此也作出了验证，发现确实能够出现水平滚动条，至于高度则由内容的高度决定，但不会出现垂直滚动条。需要注意的是注释里面大家很容易出现for循环，就不能避免使用<或则>等，我们的本意是注释里面使用比较，但是ASDoc会把这些识别为标签，这样就会出现错误，我的办法是使用中文的《或》来标示小于等于，你们有别的办法请告诉我，互相学习。

　　4、@return标记

　　@return针对一个方法的返回值进行说明。也就是说此标记是用于方法中的注释的。其中其书写格式如下：

　　　　@return 说明文字

　　下面看一下例子：

　　源代码：　

        /**
         * 获取名字
         * @return 返回名字
         */
        public function getName():String
        {
            return "追梦的远远";
        }

　　效果：

　　

　　从上图可见，我们在注释中并没有在@return中写明返回值的类型，但是在生成的文档中确能够显示返回值类型，这其实是ASDoc能够自动识别方法返回值的类型，所以并不需要我们指定。那对于无返回值的方法（也就是返回值类型为void的方法）如果加上这个标记没有效果。

　　5、@see标记

　　@see标记的作用是生成一个参考引用。在一些情况下某些类、属性或者方法在其他地方有进行说明或者引用，这时候我们可以通过此标记来引用此例子来进行说明。其书写格式如下：

　　　　@see 引用 [说明文本]

　　看如下例子：

　　源代码：　

        /**
         * 获取名字
         * @see MyCeShi#getNameById()[文字说明]
         * @return 返回名字
         */
        public function getName():String
        {
            return "追梦的远远";
        }

　　效果：

　　

　　如图所示，getName方法下多出了一栏另请参见（See also）的信息，在这栏里面就有刚才所写的getName方法的引用。可能你会问@see标记中的引用部分应该怎么写呢？其实对于引用类内部方法来说是通过锚点来实现的，所以引用部分就是填写一个锚点（如果要引用到当页的锚点，学个HTML的朋友就知道是用#锚点名称）。其实用ASDoc生成的方法和属性都带有一个锚点的，其规律就是方法的锚点就是方法名称()（一定要加括号），属性的锚点就是属性名称。

　　对于如果一个类、方法或属性中有多个参考引用的地方我们可以使用多个@see来进行引用，这是ASDoc中所允许的。

　　根据追梦的总结，对于@see标记的引用参数的写法应该是(分别对于类、方法和属性)：

　　　　包路径.类名称

　　　　包路径.类名称#方法名称()

　　　　包路径.类名称#属性名称

　　如果是类内的方法则可以省略包路径.类名称部分。

　　6、@private标记

　　此标记的作用是，当你的部分类、方法或属性不想公开给其他人看到的时候，可以在相应的地方加上此标记。那么ASDoc将不会生成此部分的文档说明。其书写格式如下：

　　　　@private

　　源代码：

　　

        /**
         * @private
         * 获取名字
         * @see MyCeShi#getNameById()[文字说明]
         * @return 返回名字
         */
        public function getName():String
        {
            return "追梦的远远";
        }