Flex Ant MXMLC/COMPC/html-Warpper/AsDoc tasks

你可以使用mxmlc任务来编译Flex的应用程序(Application), 各种模块(modules)，以及样式表(CSS).  mxmlc任务支持Flex命令mxmlc的多数编译参数，包括aliases.
参考:
Using mxmlc, the application compiler
http://livedocs.adobe.com/flex/3/html/help.html?content=compilers_13.html
获取更多关于使用mxmlc命令的信息。
Required attributes
mxmlc任务需要一个指定了要编译MXMl文件的file属性。在命令行模式下mxmlc命令并没有和mxmlc任务的file属性等效的参数， 因为命令行下要编译的的文件是默认参数。(例如：cmd模式，mxmlc c:/myfiles/app.mxml；或是mxmlc -option arg1 arg2 arg3 –target_file.mxml)
Unsupported options
mxmlc任务不支持help和version编译参数：
Example
在下面的例子中mxmlc任务显式地定义了source-path和library-path参数，并且也添加了incremental和 keep-generated-actionscript参数。该例还指定了输出目录output。例中定义了main和clean俩个任务，main任 务用于将Main.mxml文件编译成swf文件，clean用于删除之前输出目录。

<?xml version="1.0" encoding="utf-8"?>
<!-- myMXMLCBuild.xml -->
<project name="My App Builder" basedir=".">
    <taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />
    <property name="FLEX_HOME" value="C:/flex/sdk"/>
    <property name="APP_ROOT" value="apps"/>
    <property name="DEPLOY_DIR" value="c:/jrun4/servers/default/default-war"/>
    <target name="main">
        <mxmlc
            file="${APP_ROOT}/Main.mxml"
            output="${DEPLOY_DIR}/Main.swf"
            actionscript-file-encoding="UTF-8"
            keep-generated-actionscript="true"
            incremental="true"
        >
            <!-- Get default compiler options. -->
            <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>

            <!-- List of path elements that form the roots of ActionScript
            class hierarchies. -->
            <source-path path-element="${FLEX_HOME}/frameworks"/>

            <!-- List of SWC files or directories that contain SWC files. -->
            <compiler.library-path dir="${FLEX_HOME}/frameworks" append="true">
                <include name="libs" />
                <include name="../bundles/{locale}" />
            </compiler.library-path>

            <!-- Set size of output SWF file. -->
            <default-size width="500" height="600" />
        </mxmlc>
    </target>
    <target name="clean">
        <delete dir="${APP_ROOT}/generated"/>
        <delete>
            <fileset dir="${DEPLOY_DIR}" includes="Main.swf"/>
        </delete>
    </target>
</project>

=====================================================
我们可以使用compc任务将组件编译成swc文件。compc支持Flex命令compc的多数编译参数，包括aliases.
参考:Using compc，the component compiler
http://livedocs.adobe.com/flex/3/html/help.html?content=compilers_13.html
获取更多关于使用mxmlc命令的信息。
Required attributes
compc任务的唯一一个必要属性就是output属性，output指定了编译生成的swc文件的名称。
Special attributes
include-classes属性可以用一系列的以空格分开的类名作为参数值。例如

<compc include-classes="custom.MyPanel custom.MyButton" ... >
    ...
</compc>

include-resource-bundles属性，我们不能给该属性的某一个入口指定一系列以逗号或空格分开的值作为参数。相反，我们需要为每个所需引入的resource bundle单独嵌套一个include-resource-bundles标签。

<compc output="${swf.output}/compc_rb.swc" locale="en_US">
    <include-resource-bundles bundle="ErrorLog"/>
    <include-resource-bundles bundle="LabelResource"/>
    <sp path-element="locale/{locale}" />
</compc>

Unsupported options
compc任务不支持help和version参数。
Example
下面的例子中compc任务将编译生成swc文件，其中包括2个自定义组件以及一些资源文件。组件是通过include-classes属性来添加 的，源文件在components子目录中。资源文件，包括4个图片和一个css文件通过include-file元素添加到swc中。例中定义了 main和 clean俩个targets，main用于编译生成MyComps.swc文件， 而clean用于删除main任务所输出的文件。

<?xml version="1.0" encoding="utf-8"?>
<project name="My Component Builder" basedir=".">
    <taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />
    <property name="FLEX_HOME" value="C:/flex/sdk"/>
    <property name="DEPLOY_DIR" value="c:/jrun4/servers/default/default-war"/>
    <property name="COMPONENT_ROOT" value="components"/>
    <target name="main">
        <compc
            output="${DEPLOY_DIR}/MyComps.swc"
            include-classes="custom.MyButton custom.MyLabel">
            <source-path path-element="${basedir}/components"/>
            <include-file name="f1-1.jpg" path="assets/images/f1-1.jpg"/>
            <include-file name="f1-2.jpg" path="assets/images/f1-2.jpg"/>
            <include-file name="f1-3.jpg" path="assets/images/f1-3.jpg"/>
            <include-file name="f1-4.jpg" path="assets/images/f1-4.jpg"/>
            <include-file name="main.css" path="assets/css/main.css"/>
        </compc>
    </target>
    <target name="clean">
        <delete>
            <fileset dir="${DEPLOY_DIR}" includes="MyComps.swc"/>
        </delete>
    </target>
</project>

=========================================================

html-wrapper任务生成我们部署Flex applications所需的文件。HTML wrapper由<object>和<embed>标签组成，<object>和<embed>标签会 把swf文件嵌在HTML页面中。
html-wrapper任务生成index.html和 AC_OETags.js文件。如果你允许linking support，则html-wrapper任务还会输出deep linking文件， 如historyFrame.html, history.css和history.js等；如果你允许express installation，则html-wrapper任务会生成playerProductInsta.swf文件。
一般来说，我们需要把上述文件和Flex程序一起部署到web服务器上。用户请求的就是嵌入了swf文件的HTML wrapper。我们也可以在Ant编译之后自定义这些支持文件。参考Creating a Wrapper获取更多HTML wrapper的信息。
About the templates
使用html-wrapper任务我们可以生成6种类型的HTML wrapper模板。
1. Client-side detection only — 提供探测客户端player版本的脚本，在版本过低时返回可以更换的内容。
2. Client-side detection with history — 除了Client-side detection之外，还添加了deep linking suppor。
3. Express installation — 提供支持Express Install功能的脚本。
4. Express installation with history — 提供支持Express Install和deep linking的脚本。
5. No player detection — 提供最基本的wrapper。
6. No player detection with history — 提供仅支持deep linking的wrapper
Supported attributes
html-wrapper任务的属性与<object>和<embed>标签的某些属性类似，另外它还支持output和templenate属性，其中output用于指定输出目录，template用于指定wrapper的类型。
参考:About the object and embed tags,
http://livedocs.adobe.com/flex/3/html/help.html?content=wrapper_13.html#166446##166446
获取<object>和<embed>标签属性的完整列表。
下表描述了html-wrapper任务所支持的属性
参考 http://livedocs.adobe.com/flex/3/html/help.html?content=anttasks_1.html
Required attributes
html-wrapper任务需要指定swf属性. 另外如果你只指定了swf属性, 默认的wrapper会有以下默认的设置：
height="400"
width="400"
template="express-installation"
bgcolor="white"
history="false"
title="Flex Application"注意要使用包含扩展名的文件名来给swf属性赋值，html-wrapper会自动在swf属性值的后面添加.swf后缀。例如
swf="Main"不要使用
swf="Main.swf"Unsupported options
html-wrapper任务并不能设置<object>和<embed>标签的所有参数，这其中不支持的参数包括quality, allowScriptAccess, classid, pluginspage和type等.
Example
下面的例子包括wrapper和clean俩个targets， wrapper 生成支持deep linking和player detection的HTML wrapper，clean用于删除wrapper生成的所有文件。

<?xml version="1.0" encoding="utf-8"?>
<!-- myWrapperBuild.xml -->
<project name="My Wrapper Builder" basedir=".">
    <taskdef resource="flexTasks.tasks" classpath="${basedir}/lib/flexTasks.jar"/>
    <property name="FLEX_HOME" value="C:/flex3/sdk"/>
    <property name="APP_ROOT" value="apps"/>
    <target name="wrapper">
        <html-wrapper
            title="Welcome to My Flex App"
            file="index.html"
            height="300"
            width="400"
            bgcolor="red"
            application="app"
            swf="Main"
            version-major="9"
            version-minor="0"
            version-revision="0"
            history="true"
            template="express-installation"
            output="${APP_ROOT}"/>
    </target>
    <target name="clean">
        <delete>
            <!-- Deletes playerProductInstall.swf -->
            <fileset dir="${APP_ROOT}"
                includes="playerProductInstall.swf"
                defaultexcludes="false"/>
            <!-- Deletes index.html and historyFrame.html -->
            <fileset dir="${APP_ROOT}" includes="*.html" defaultexcludes="false"/>
            <!-- Deletes history.css -->
            <fileset dir="${APP_ROOT}" includes="*.css" defaultexcludes="false"/>
            <!-- Deletes history.js and AC_OETags.js -->
            <fileset dir="${APP_ROOT}" includes="*.js" defaultexcludes="false"/>
        </delete>
    </target>
</project>

===================================================

在所在工程中新建一个properties文件,用以保存相关配置, 同时建立一个bulid.xml, 用以提供ANT配置文件.
具体实现:
1:  为便于管理与配置, 将ASDoc的参数放置于一个properties文件中, 在本例中我们取名叫做: asdoc.properties
含如下信息:
FLEX_HOME = E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\FBPlug-in301\\sdks\\3.1.0
asdoc.exe  = E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\FBPlug-in301\\sdks\\3.1.0\\bin\\asdoc.exe
dir.docSource = com\\insprise\\localizationeditor
dir.src  = .
dir.output =  E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\workspace\\AIRTest\\doc
main.title = Test
window.title  =  test
footer  = Insprise Software
以上提供了ASDoc的路径, 源文件的目录, 文档输出目录, 以及文档的网页标题, 文档内标题, 文档页脚等信息.
2: Build.xml配置:

<project name="ASDoc build" default="main">
  <!-- 定义ASDoc变量/参数来源 -->
  <property file="asdoc.properties"></property>
  <!-- main target:删除旧文档,生成新文档 -->
  <target name="main" depends="clean_Old_Docs, create_Docs">
     <!-- 删除旧文档 -->
    <target name="clean_Old_Docs">
      <delete dir="${dir.output}"/>
      <mkdir dir="${dir.output}"/>
    </target>
    <!-- 生成新文档 -->
    <target name="create_Docs">
      <exec failonerror="true" executable="${asdoc.exe}">
        <arg line="-source-path '${dir.src}'"/>
        <arg line="-doc-sources '${dir.docSource}'"/>
        <arg line="-main-title '${main.title}'"/>
        <arg line="-window-title '${window.title}'"/>
        <arg line="-footer '${footer}'"/>
        <arg line="-output '${dir.output}'"/>
        <arg line="-library-path '${FLEX_HOME}\frameworks\libs'"/>
        <arg line="-library-path '${FLEX_HOME}\frameworks\libs\air'"/>
      </exec>
    </target>
  </target>
</project>

ANT运行build.xml之后,将会自动生成文档到输出目录.
当ANT编译成功后,会出现如下提示[这个是在Eclipse中使用ANT编译后的输出信息]:
Buildfile: E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\src\build.xml

clean_Old_Docs:

[delete] Deleting directory E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\doc

[mkdir] Created dir: E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\doc

create_Docs:

[exec] Loading configuration file E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\FBPlug-in301\sdks\3.1.0\frameworks\flex-config.xml

[exec] Documentation was created in E:\eclipse-jee-europa-fall2-win32_FB3\eclipse\workspace\AIRTest\doc\

main:
BUILD SUCCESSFUL
Total time: 26 seconds

=======================================================

在没有使用ASDoc之前, 我的注释总是乱七八糟, 并且胡说八道. 该讲的没有讲清楚, 废话比代码还多. 自从抱着试试看的态度用了一下ASDoc, 俺决定认真参照公司的代码规范, 认真规范下俺不曾被规范的注释.
ActionScript注释生成工具很多, 但俺们唯独使用ASDoc.
首先, 总结下ActionScript注释规范:
我该牢记的, 各参数出场顺序:
@param
@return
@throws
@see
如:
/**
* 解析给定的I18N语言字符串, 并通过fieldStringToLocalizationItem将之转换为LocalizationItem对象,放入到ArrayCollection中.
* @example 处理里一串I18N语言字符串
*
* stringToAC('{zh=简体中文}{zh_tw="繁体中文"}', false);
*
* @param s:String 待处理的字符串
* @param strict:Boolean 是否采用严格机制来处理, 默认为ture,意为如果字符串不合要求则报错; 可指定为False, 忽略错误,完成操作.
* @return 处理完后包含有LocalizationItem的ArrayCollection; 如果制定的字串为NULL,则返回一个空的ArrayCollection;
* @throws Error 如果strict为true,在检测到字符串不合要求时会throw Error.
* @see #fieldStringToLocalizationItem()
*/
public static function stringToLocalizationItems(s:String, strict:Boolean = true):ArrayCollection {
....
}需要注意的一个地方是@see,  当需要see某个类中的函数时
@see Array#pop();
需要see本类某函数时,如需要see下本类的 fieldStringToLocalizationItem(fieldString:String, strict:Boolean = true)函数, 则|
@see #fieldStringToLocalizationItem()
其次,总结下ASDoc里重要的配置参数
-source-path, 该path指明了源代码存放的位置
-doc-classes, 需要生成目录的类 , 在使用该变量之前必须已经声明-source-path;
如: asdoc -source-path . -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo 则意味着生成当前目录下,comps\GraphingWidget .as 与comps\GraphingWidgetTwo.as的文档
-doc-sources: 指定某目录, 生成该目录及其子目录下所有.as文件的注释. 可以单独直接使用,也可以配合使用-source-path. 如:
doc-sources E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\workspace\\AIRTest\\com\\insprise
或配合使用:
-doc-sources   com\\insprise
-source-path   E:\\eclipse-jee-europa-fall2-win32_FB3\\eclipse\\workspace\\AIRTest\\com\\insprise
其他信息基本上都是无关紧要不痛不痒的一看明白.

===========================================================

运用ASDoc工具
原文地址: http://livedocs.adobe.com/flex/3/html/asdoc_9.html
译者注：
ASDoc是adobe官方提供的ActionScript的API文档生成工具，现在已经集成在FlexBuilder3中
打开ASDoc工具的方法：
1.安装FlexBuilder3后，
打开    开始—>程序—>Adobe—>Adobe Flex 3 SDK Command Prompt
2.此时会进入cmd命令行界面，用cd命令进入你的工程目录下
例如我的工程目录是E:\flexwork
当前是cmd指向在C:\Program Files\Adobe\FLexBuilder3\
3.首先输入 E:进入E:\
然后 输入 cd flexwork
屏幕显示E:\flexwork\>  后即可使用asdoc命令编译API文档了
编译后的asdoc文档会在E:\flexwork\路径下输出一个asdoc-output文件夹，运行里面的index.html就是API文档主页
你可以使用以下的ASDoc命令参数来制定类文件列表
doc-classes       doc-sourcess       doc-namespaces
doc-classes和doc-namespaces要求用source-path指定类文件文件所在的根目录
如下是一个最基本的列子，用doc-classes参数指定类文件列表：
asdoc –source-path . –doc-classes comps.CraphingWidget comps.GraphingWidgetTwo
这 个例子中，类文件必须是comps\GraphingWidget.as和comps\GraphingWidgetTwo.as,并且comps必须是 位于运行asdoc命令所在位置下的一个子文件夹。doc-classes的参数中用‘.’对应类所在的包(package)名
译者注：如果类文件就在当前目录下，source-pathh参数后面的内容需要填写’.’
如果类文件没有在当前目录下，可以用source-path参数指定该目录。
下面的例子，如果两个类文件在C:\flex\class_dir\comps下，可以像这样使用asdoc命令：
asdoc –source-path C:\flex\class_dir\comps –doc-classes comps.CraphingWidget comps.GraphingWidgetTwo
如果你的程序里引用了包含有swc文件的库。
在下例中，可以使用 –library-path参数指定要包含的swc文件：
asdoc –source-path . –doc-classes myComponents.BlueButton –library-path C:\myLibs
用 doc-sources参数可以指定源文件夹。通过该参数，asdoc会递归搜寻目录。
下面的命令会生成当前目录及其子目录下所有的类：
asdoc –source-path . –doc-sources
用 doc-namespaces参数可以指定要输出的命名空间。
下面的命令会把core framework下的所有类文件输出成文档：
asdoc -source-path frameworks -namespace http://framework frameworks/core-framework-manifest.xml -doc-namespaces http://framework
排除类文件
用doc-classes, doc-sources和 doc-namespaces命令输出所有的类文件时，
会有以下三点例外：
用exclude-classes参数指定的类不会输出
类中包含了@private标签的不会被输出
SWC中的类，不会被输出
以下的例子中，会输出当前目录及其子目录下所有类文件，除了comps\PageWidget 和 comps\ScreenWidget.as：
asdoc -source-path . -doc-sources . -exclude-classes comps.PageWidget comps.ScreenWidget
注意：
这些被排除的类，仍然会同其他类一样被编译，只是内容不会被输出
如果将exclude-dependecies参数设为true，当编译类时所依赖的相关类不会被输出。
该参数默认值是false，意味着所有与指定类相关联的类都会被正常输出成文档。
例如：你用doc-classes指定了类A,如果类A中 import了类B，那么类A和类B都会被输出。
asdoc命令参数列表：
asdoc命令参数使用方法等同于mxmlc和compc
更多的mxmlc和comp信息，参见 Using the flex Compilers
参数功能列表如下：
OptionDescription
-doc-classes path-element [...]指定需要被输出成文档的类文件，这些类文件必须放在资源路径下[默认参数]
该参数使用方法等同于compc组件编译器的-include-classes参数，更多信息参见 Using compc, the component compiler
-doc-namespaces uri manifest要求被输出成文档的类文件URIs列表，这些类文件必须放在资源路径下。
必须包含至少一个URI并指出命名空间内容的明确位置
该参数使用方法等同于compc组件编译器的-include-namespaces参数，更多信息参见Using compc, the component compiler
-doc-sources path-element [...]需要被输出成文档的文件目录，并且其子目录也会被递归输出
该参数使用方法等同于compc组件编译器的-include-sources参数，更多信息参见Using compc, the component compiler
exclude-classes string不需要被输出的类文件列表，必须指定类名
或者， 该类中的ASDoc命令里包含了 @private 标签，同样也不会被输出
-exclude-dependencies true|false        决定是否所有的相关类都会输出，如果设true，与输出类相关的类不回被输出。默认值为false
-footer string文档中HTML页面底部的显示信息
-left-frameset-width int控制文档左边目录宽度的整数值。你可以根据你的包名来改变这个值
默认值是210px
-main-title “string”文档中HTML页面头部显示信息
默认值是”API Documentation”.
-output string输出文档的目录名. 默认值 “asdoc-output”.
-package name “description”输出文档中对应的包名。你可以指定一个以上的包
下例中，输出了两个包：
asdoc -doc-sources my_dir -output myDoc -package com.my.business “Contains business classes and interfaces” -package com.my.commands “Contains command base classes and interfaces”
-templates-path stringASDoc模板目录的路径. 默认值是ASDoc 安装目录下的asdoc/templates。该目录包含了用于输出成文档的所有的HTML, CSS, XSL文件image
-window-title “string”文档中浏览器顶部显示信息
默认值是”API Documentation”.

以下asdoc命令适用于compc组件编译器:
-source-path
-library-path
-namespace
-load-config
-actionscript-file-encoding
-help
-advanced
-benchmark
-strict
-warnings
更多信息，参见 Using mxmlc, the application compiler 还有很多其他程序编译参数可以使用，这里不再详加阐述，在ASDoc tool中你可以像使用mxmlc and compc一样使用同样的命令构造文件。

本文来源于 冰山上的播客 http://xinsync.xju.edu.cn ,
原文地址：http://xinsync.xju.edu.cn/index.php/archives/category/prglang/flex/flex3/page/2