使用asDoc生成自己的Flex API Document

概述一：

运用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

参数功能列表如下：

 

Option

Description

 

-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 string

ASDoc模板目录的路径. 默认值是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一样使用同样的命令构造文件。

文章来自: 闪客居(www.flashas.net) 详文参考：http://www.flashas.net/html/FLASHfuzhuruanjian/20090106/3877.html

 

概述二：

 

ASDoc是adobe官方提供的ActionScript的API文档生成工具，现在已经集成在FlexBuilder3中；
使用ASDoc工具可以生成和Adobe的ActionScript3帮助一样的文档，使用的方法如下：

========== 本人*作成功的过程如下...火舞天涯http://blog.csdn.net/cjy37

 

英文配置：http://bhsc-happy.iteye.com/blog/320222

Run -> External Tools -> Open External Tools Dialog ....

1、New 一个项目，并命名！
2、主要是设置Main选项卡：
1)、Location: 填asDoc.exe所在的路径 C:/Program Files/Adobe/Flex Builder 3/sdks/3.2.0/bin/asdoc.exe
2)、Working Directory: 填工程中，代*所在的目录 ${workspace_loc:/HTFlexLib/src}
3)、Arguments: 最重要的就是这里了，这里填的是AsDoc的编译参数 -source-path=. -doc-sources=${workspace_loc:/HTFlexLib/src} -output="../../FlexDoc" -external-library-path="D:/work/flexWordFolders/flex3/libs/gearWheel.swc"
-------------------- 参数说明 ----------------------
-source-path：代*所在的目录（不能用中文目录）
-doc-sources：文件所在的目录（不能用中文目录）
-output： 输出文档的目录（不能用中文目录）
-external-library-path：扩展的Lib路径（外部的swc的路径）（不能用中文目录）
3、为了AsDoc输出的文档支持中文的注释。
切换到Common选项卡，Console Encoding分组项目 -> 选择Other -> 选择UTF-8

...火舞天涯 http://blog.csdn.net/cjy37===============

好，OK了，接着点Run～！ 文档就生成了，赶快去看看吧～！

 

参考的文章：http://www.flashas.net/html/FLASHfuzhuruanjian/20090106/3877.html

 

注：在MXML文件中如果有类似以下引用图标资源文件者，会报错：

 

[Bindable]
[Embed(source='assets/icon_alert.png')]
private var alert_icon:Class;

 

解决的办法是创建一个资源类*.as类型的，专门保存一些图标等资源。如：

 

[Bindable]
public class HtAssets
{
  [Embed(source='assets/icon_alert.png')]
  public var alert_icon:Class;

  [Embed(source='assets/card.gif')]
  public var card_icon:Class;

  [Embed(source='assets/document.png')]
  public var document_icon:Class;

  public function HtAssets()
  {
  }

  static public function iconClass(s:String):Class
  {
    var tmpAssets:HtAssets=new HtAssets();

    return tmpAssets[s];
  }

}

 

引用办法：

 

[Bindable]
public var card_icon:Class=HtAssets.iconClass("card_icon");