AS3 AsDoc 介绍、使用

ASDoc是adobe官方提供的ActionScript的API文档生成工具，现在已经集成在FlexBuilder3中。笔者这段时间才刚刚接触到这个工具，所以在网站也搜索了一些资料来对这个工具作进一步的了解。不过中文的资料对此工具的介绍和使用也不是太多，经过我几天的努力，对一些国外资料的研究和总结写了以下这篇文章，这篇文章主要是对ASDoc在注释中所使用的标签作了一些深入的研究，现在把我在探索的这个过程中的一些心得分享给大家。

首先在这里要先介绍一下API文档生成形式格式和结构，为了了解ASDoc的生成形式，在第一个例子中将不采用任何ASDoc标记来注释类。类定义如下：

package{

       public class Demo{

              private static const const_1:int;

              protected static const const_2:String;

              public static const const_3:Boolean;

             

              private static var static_private_variable:int;

              protected static var static_protected_variable:String;

              public static var static_public_variable:Boolean;

             

              private static function static_private_method():void{

              }

              protected static function static_protected_method():void{

              }

              public static function static_public_method():void{

              }

             

              private var private_variable:int;

              protected var protected_vairable:String;

              public var public_variable:Boolean;

             

              public function Demo(){

              }

             

              public function public_method():void{

              }

             

              protected function protected_method():void{

              }

             

              private function private_method():void{

              }

       }

}

其包含了所有类相关的定义，运行ASDoc来生成此类文档（在输入命令使需要注意-source-path如果不在当前目录时需要自己指定，而且必须使用-doc-classes、-doc-namespaces或者-doc-sources来指定那些类、名称空间或者源码）。

笔者发现生成后的文档静态公有的属性会和公有属性组织在一起，而静态受保护属性会和受保护属性组织在一起；方法也如此。同时私有成员是不会体现在文档之中。其实，这些可以根据Flex的帮助文档就可以知道了，为了有一个好的开始，还是先进行了一下这样的测试。接着下来将逐步介绍ASDoc标记的用法以及一些ASDoc的参数使用。

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

/**

* 注释内容

* */

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

@param标记

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

@param 参数名称 参数说明

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

现在我们来为Demo写一个函数print，然后我们来生成文档看一下文档格式如何，其中函数定义如下：

/**

* 输出信息

* @param info 需要输出信息的对象

* */

public function print(info:Object):void{

}

在命令行输入：D:\study\asdoc>asdoc -doc-classes Demo -output doc\ -source-path .

其输出格式为：

‍

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

/**

* 输出信息

* @param firstParam 需要输出信息的对象

* @param secondParam 输出格式

* */

public function print(info:Object,format:String):void{

}

其输出格式是：

‍

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

@example标记

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

@example 例子的说明性文字

<listing version=”3.0”>

例子的代码

</listing>

从格式中可知，例子的代码是写在<listing />标记之中的，下面通过一个例子来说明一下，还是以print函数为例：

/**

* 输出信息

* @param firstParam 需要输出信息的对象

* @param aaaaaaa 输出格式

* @example 下面例子是通过print函数输出信息。

* <listing version="3.0">

* var i:int=1;

* var demo:Demo=new Demo();

* demo.print(i,"%d");

* </listing>

* */

public function print(info:Object,format:String):void{

}

其输出格式为：

‍

从上图可见，在@example后面的文字输出在Example的下面，此文字是用来对例子的一个说明。然后写在<listing />标记中的代码就放在一个灰色的矩形框中。根据官方的帮助说明，在个框是带水平滚动条的，所以当内容超出一定长度后就会显示水平的滚动条。笔者对此也作出了验证，发现确实能够出现水平滚动条，至于高度则由内容的高度决定，但不会出现垂直滚动条。如下图所示：

‍

@return标记

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

@return 说明文字

下面往类中来添加一个新的方法getString来进行说明：

/**

* 返回一个字符串

* @return 返回一个字符串

**/

public function getString():String{

   return "demo";

}

用ASDoc来进行生成文档，其格式如下图所示：

‍

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

/**

* 输出信息

* @param info 需要输出信息的对象

* @param format 输出格式

* @return 该函数无返回值

* @example 下面例子是通过print函数输出信息。

* <listing version="3.0">

* var i:int=1;

* var demo:Demo=new Demo();

* demo.print(i,"%d");

* </listing>

* */

public function print(info:Object,format:String):void{

}

其输出格式为：

‍

从图中可见，即使我们写上了@return标记，当ASDoc检测到该方法是无返回值时，他会自动过滤掉@return所作的说明。

@see标记

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

@see 引用 [显示文本]

为了更好的理解其含义，我将在原来的print方法中引入getString方法，然后getString方法中则采用@see标记来进行参考引用。

/**

* 输出信息

* @param firstParam 需要输出信息的对象

* @param aaaaaaa 输出格式

* @return 该函数无返回值

* @example 下面例子是通过print函数输出信息。

* <listing version="3.0">

* var i:int=1;

* var demo:Demo=new Demo();

* demo.print(demo.getString(),"%s");

* </listing>

* */

public function print(info:Object,format:String):void{

}

/**

* 返回一个字符串

* @return 返回一个字符串

* @see #print()

**/

       public function getString():String{

       return "demo";

}

生成文档后，输出样式如下：

‍