ASDOC文档撰写和生成

 

一 文档编写

1 as 中文档编写。

1-1 类注释文档编写

在类的上方使用下面标准注释

如果类带[Bindable] 和[RemoteClass]标签，则注释一定要在类声明上一行。

检验方法，可以使用鼠标悬停在类上。或者选中类名，使用F2查看。

示例如下：

 

[RemoteClass(alias="org.swflash.model.Account")]
[Bindable]
/*******************************************
 * 账户管理的VO
 * <p>创建者: swflash</p>
 *******************************************/
public class AccountVO extends BaseVO

 

 

1-2 方法注释编写

方法参数，可以使用@param 标签 ，返回值使用@return 标签。

每个参数的说明可以使用@param paramName 注释xxx 的格式进行描述

方法还可以使用@see标签，要求参看其它方法。

 

/**
 * 将数据转换为JSON字符串
 * @param  obj 对象
 * @return JSON字符串
 */
public static function vo2String(obj:Object):String

 

 

1-3 类属性变量编写

直接在类属性上编写。

 

 

[IDField(name="accountId")]
/**
 * 账号的主键
 * */
public var accountId:String;

 

 

1-4 事件注释文档编写

使用@eventType 标签，并表明对应的事件类型，以及事件名称。

 

/**
 *  分发保存事件
 *  @eventType flash.events.Event.FORM_SAVE
 */

 

 

注：如果对javadoc熟悉，可以参考javadoc 

 

2 mxml中文档编写。

 

2-1 类注释文档编写

使用<!--- -->编写。注意使用的是三条“-”

 

<?xml version="1.0" encoding="utf-8"?>
<!---
测试用例的容器
-->
<mx:HDividedBox xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
width="100%"
height="100%"
>

 

 

2-2 成员属性编写。同样是三条“-”。

 

<!---顶部菜单-->
<buzcomp:BannerMenu id="bannerMenu"
moduleDP="{moduleList}"
permissionList="{permissionList}"
sideMenu="bannerMenu_sideMenuHandler(event)"
customMenu="bannerMenu_customMenuHandler(event)"
bannerMenu="bannerMenu_bannerMenuHandler(event)"/>

  

 

二 文档生成

1 使用external tool

1-1 配置asdoc 的external tools 

-load-config+=asdoc-config.xml

1-2配置console输出。

 注意选择ISO-8859-1

 

注意：默认情况下，会有乱码在控制台，如果不选择iso-8859-1，在log文件中会乱码。

 

2 config的配置如下：

 

<?xml version="1.0"?>
<flex-config xmlns="http://www.sunwaysoft.com/2011/flex-config">
<!--编译参数-->
    <compiler>
     <!--源文件路径--> 
        <source-path>
            <path-element>src</path-element> 
        </source-path>
        <!--依赖包路径-->
        <external-library-path>
     <path-element>../SwflashFlex/depend.lib</path-element>
     </external-library-path>  
    </compiler>
    <!--需要生成文档的目录-->
    <doc-sources>
     <path-element>src/org/swflash/common</path-element>
     <path-element>src/org/swflash/frame</path-element>
    </doc-sources>
 <!--需要排除的文件-->
<!--测试和调试的时候用得上-->
    <exclude-sources>
                <path-element>src/org/swflash/util/helper/DataGridHelper.as</path-element>
                <path-element>src/org/swflash/model/common/vo/EmployeeVO.as</path-element>
    </exclude-sources>
    -->
    <!--文档浏览器标题-->
    <window-title>
     Swflash Flex API说明文档
    </window-title>
    <!--文档顶部-->
    <main-title>
     Flash2Swf® SwflashLib® 语言参考
    </main-title>
    <!--文档底部-->
    <footer>
     © 2010 Flash2Swf . All rights reserved.
    </footer>
</flex-config>

 

 

 

其它：

1 代码中的注释出现的html标签必须成对。

2 代码中不要出现而外的注释标签，比如”@版权所有“之类。

3 生成文档过程中会先编译代码，继而生成文档，所以代码中不能够存在编译错误。

4 生成文档过程中，原则上会输出异常到log和validation_errors.log 中，但是实际上有时候并不输出，需要逐一仔细排查。

 

 

 

参考链接

http://help.adobe.com/en_US/flex/using/WSd0ded3821e0d52fe1e63e3d11c2f44bc36-7ffa.html