【转】探索ASDoc:标签篇-@example|@includeExample|@exampleText标签

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

转自云の部族


@example标记

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

@example 例子的说明性文字 <listing version=”3.0”> 例子的代码 </listing>

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

/**
* 输出信息
* @param firstParam 需要输出信息的对象
* @param aaaaaaa 输出格式
* @example 下面例子是通过print函数输出信息。
* 
* var i:int=1;
* var demo:Demo=new Demo();
* demo.print(i,"%d");
* 
* */
public function print(info:Object,format:String):void
{
}

其输出格式为:

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

@includeExample标记

此标记是引入一个外部示例文本到ASDoc输出中。ASDoc将从由ASDoc工具的-examplespath参数指定的基于类的包名或者目录来搜索示例文件。

例如,你将示例路径参数设置为 c:\eamples 。然后为 mx.controls.Button 类添加一个示例。他发生在 c:\exmples 目录下的 mx\controls\directory 里面,即是 c:\examples\mx\controls directory。你可以进一步用 @includeExample 标记来指定文件的位置。例如,你指定的 @includeExample 标记如下所示:

@includeExample buttonExample/ButtonExample.mxml

ASDoc将从 c:\examples\mx\controls\buttonExample 目录下进行查找此示例。如果在一个类注释中插入此标记,这个例子将显示在输出的HTML文档的最后面,如果你在一个类的元素中插入此标记,那么示例将出现在该元素的详细说明中。

其书写格式如下:

@includeExample 示例文件路径

下面来通过示例看一下生成的文档样式如何,先建立一个示例文件example.txt,然后在SubDemo中运用@includeExample来引入此文件,代码如下:

example.txt文件内容

//这是一个例子文件
var demo:Demo=new Demo();

SubDemo类

package{
       /**
       * Demo的子类
       * @internal 这是一个内部文本,不在文档中显示的。
       * @includeExample example.txt
       * */
       public class SubDemo extends Demo{
              public function SubDemo(){
              }
              /**
              * @inheritDoc
              * @throws Exception 异常
              **/
              override public function getString():String{
                     return "sub";
              }
       }
}

上面步骤完成后,接下来要生成文档了,这时候要注意的是,asdoc中要指定一下-examples-path这个参数,如果不指定的话就会提示找不到外部示例文件。最终命令行内容如下:

asdoc -source-path . -doc-classes Demo Demo2 fi.events.DemoEvent SubDemo Exception -output doc/ -examples-path .

生成后效果如下图所示:

@exampleText标记

此标记是使用在一个通过@includeExample标记引入外部的示例文件中。其书写格式如下:

@exampleText 说明文本

通过此标记可以在例子的前面或者后面加上一个对例子的注释说明。其中外部例子是支持例子前后加注释的,所以标记也限定了加入ASDoc注释的位置,只能是例子的第一行前面或者例子的最后一行后面。如果加入到中间的话,那么后面的所有文本都会被ASDoc所丢弃。

下面的例子来说一下其用法,首先在原来@includeExample的例子基础上往example.txt加上注释代码,如下所示:

/**
* @exampleText 这是一个例子文件
**/
//这是一个例子文件
var demo:Demo=new Demo();
demo.getString();

然后生成文档,效果如下图所示: