在Flash Builder 4.x 中书写符合ASDOC规范的说明注释

概述

本文介绍和总结Flex中的说明注释——ASDOC注释的规范及注意事项。

知识点

• ASDOC说明注释
• 可用的说明注释标签
• 可用的HTML标签
• 注释编写注意事项

Flex中的ASDOC说明注释

与其它语言一样，Flex支持单行注释、块注释和说明注释。说明注释是一种特殊的块注释，可使用丰富的注释标签细化注释在IDE中的显示样式，并可通过ASDOC工具自动生成帮助文档。

在AS文档中，普通的块注释如：

/* * 普通注释 */

ASDOC说明注释如：

/** * ASDOC注释 */

可见，ASDOC注释以“/**”开始，比普通注释声明多一个“*”。

在MXML文档中，普通注释如：

<!--普通注释-->

ASDOC说明注释如：

<!---ASDOC注释-->

可见，ASDOC注释以“<!---”开始，比普通注释声明多一个“-”。

通常，在默认的设置下，普通的注释用绿色斜体字显示 ，而ASDOC注释用蓝色字显示。

在ASDOC注释中使用HTML标签

可以在ASDOC注释内容中添加HTML标签来丰富显示效果。常用的标签有：

1. <p></p> 段落
2. <br/>回车换行
3. <ol><li></li></ol>有序列表（编号）
4. <ul><li></li></ul>无序列表（项目符号）
5. <b></b>粗体
6. <i></i>斜体
7. <u></u>下划线
8. 上标
9. 下标

主要注释标签的使用

在ASDOC规范中，提供了相关标签以实现丰富的注释内容表达。常用的标签有：

1. @author 用于描述作者的相关信息
2. @param 为参数添加注释信息
3. @return 为返回值添加注释信息
4. @example 添加实例[注意：示例应写在<listing></listing>标签中附在@example之后。
5. @private 标记该注释在输出时将被隐藏
6. @default 指定默认值
7. @see 添加参考信息

see标签的使用比较复杂，主要有以下几种情况：

see注释标签的使用范例效果@see "Just a label"显示文本@see http://www.cnn.com 定位到网站@see package-detail.html 加载HTML文档@see Array指向顶层类@see AccessibilityProperties 类在当前包中@see flash.display.TextField类在其它包中@see Array#length属性在顶层类中@see flash.ui.ContextMenu#customItems属性所在类在其它包中@see mx.containers.DividedBox#style:dividerAffordance样式属性（Style property）所在类在其它包中@see #updateProperties()方法在当前类中@see Array#pop()方法在顶层类中@see flash.ui.ContextMenu#clone()方法所在类不在当前包中@see global#Boolean()方法在global中@see flash.util.#clearInterval()方法在flash.util中

范例

在默认包下建立DEMO类。代码如下：

package{        /**        * 演示        * <p>用于演示的类。</p>        * @author 某某        */        public class DEMO        {                public function DEMO()                 {                         this.test(defaultValue);                }                /**                * 默认值变量                * @default 您好！                */                public var defaultValue:String="你好！";                 /**                 * 测试                * <p>                * 用于测试的方法。                * </p>                * @param str 输入的文本。                * @return 返回输入的文本。                * @example 例子：                * <listing version="3.0">                *     var demo:Demo;                *     demo.test("你好");                * </listing>                * @author 某某                * @see DEMO                */                public function test(str:String):String                {                        return str;                }        }}

在Flash Builder代码编辑器中的动态提示效果：

ASDOC在默认模板下输出的文档（局部）：

请特别注意

1. 在AS文件中书写ASDOC注释时，注释标签、注释内容需距左侧“*”号至少一个空格的距离。否则会被系统吃掉一个字符。
2. @author等标签后面不要尾随任何除空格外的其它字符。
3. @example指定的示例仅在ASDOC工具输出的API文档中显示，在代码编辑器的动态提示中看不到。
4. @see标签后的内容不能含有HTML标签。
5. 关于ASDOC的文档输出涉及比较复杂的设置和步骤，请查阅后续相关日志。

本文为初学者的自我技术总结。不当之处欢迎指教。