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

转自云の部族

@example标记

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

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

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

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

其输出格式为：

从上图可见，在@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 标记如下所示：

1@includeExample buttonExample/ButtonExample.mxml

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

其书写格式如下：

1@includeExample 示例文件路径

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

example.txt文件内容

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

SubDemo类

 1package{
 2       /**
 3       * Demo的子类
 4       * @internal 这是一个内部文本，不在文档中显示的。
 5       * @includeExample example.txt
 6       * */
 7       public class SubDemo extends Demo{
 8              public function SubDemo(){
 9              }
10              /**
11              * @inheritDoc
12              * @throws Exception 异常
13              **/
14              override public function getString():String{
15                     return "sub";
16              }
17       }
18}

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

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

生成后效果如下图所示：

@exampleText标记

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

@exampleText 说明文本

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

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

1/**
2* @exampleText 这是一个例子文件
3**/
4//这是一个例子文件
5var demo:Demo=new Demo();
6demo.getString();

然后生成文档，效果如下图所示：