【转】探索ASDoc:标签篇-@param标签

  • 本站文章除注明转载外,均为本站原创或者翻译。
  • 本站文章欢迎各种形式的转载,但请18岁以上的转载者注明文章出处,尊重我的劳动,也尊重你的智商;
  • 本站部分原创和翻译文章提供markdown格式源码,欢迎使用文章源码进行转载;
  • 本博客采用 WPCMD 维护;
  • 本文标题:【转】探索ASDoc:标签篇-@param标签
  • 本文链接:http://zengrong.net/post/1173.htm

本文转自:云の部族


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
{
}

其输出格式是:

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