转自云の部族


@example标记

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/**
* 输出信息
* @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 标记如下所示:

1
@includeExample buttonExample/ButtonExample.mxml

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

其书写格式如下:

1
@includeExample 示例文件路径

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

example.txt文件内容

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

SubDemo类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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这个参数,如果不指定的话就会提示找不到外部示例文件。最终命令行内容如下:

1
asdoc -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
3
4
5
6
/**
* @exampleText 这是一个例子文件
**/
//这是一个例子文件
var demo:Demo=new Demo();
demo.getString();

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

留言

2010-11-25
次访问