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

本文链接：https://blog.csdn.net/capricciosoft/article/details/13277201

概述

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

知识点

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

Flex中的ASDOC说明注释

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

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

/*
 * 普通注释
 */

ASDOC说明注释如：

/**
 * ASDOC注释
 */

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

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

<!--
普通注释
-->

ASDOC说明注释如：

<!---
ASDOC注释
-->

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

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

在ASDOC注释中使用HTML标签

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

段落
回车换行
<ol><li></li></ol>有序列表（编号）
<ul><li></li></ul>无序列表（项目符号）
粗体
斜体
下划线
上标
下标

主要注释标签的使用

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

@author 用于描述作者的相关信息
@param 为参数添加注释信息
@return 为返回值添加注释信息
@example 添加实例[注意：示例应写在<listing></listing>标签中附在@example之后。
@private 标记该注释在输出时将被隐藏
@default 指定默认值
@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代码编辑器中的动态提示效果：