为你的ActionScript项目创建API文档

为你的ActionScript项目创建API文档

作为一个developer，写项目的API文档是非常重要的一件事情，flash developer也不例外。ASDoc能让我们快速创建ActionScript项目的API文档。

下面以一个实际的示例来说明如何创建API文档：

1)打开Adobe Flex 3 SDK Command Prompt。
2)用cd命令进入ActionScript项目的目录，如：cd D:\flashlizi\asdoc。
3)输入ASDoc命令：
asdoc -source-path . -window-title "ASDoc演示示例类" -package riaidea.asdoc "A Example of Using ASDoc" -doc-classes riaidea.utils.zip.ASDocExample
这是一个基本的asdoc命令。其中参数source-path表示as源文件目录，如果在当面目录则用点“.”来表示。window-title表示帮助文档的窗口标题，即浏览器窗口标题。package参数用来描述一个包，如这里描述包riaidea.asdoc为"A Example of Using ASDoc”。doc-classes用来指明需要生成API文档的类，如果指定的类中还引用了其他自定义类，那这些类也会生成API文档。
更详细的asdoc命令使用可以查看这里：http://livedocs.adobe.com/flex/3/html/index.html?content=asdoc_9.html
4)执行完毕后，在asdoc目录下会生成了一个asdoc-output目录，里面就是API文档。一般的，我们生成的API文档无需按26个字母分类，因此我们可以把里面的all-index-A.html到all-index-Z.html删除，并删除title-bar.html中的Index链接，这样的API文档就精简多了。

下面是本例中的类riaidea.utils.zip.ASDocExample的源码：

package riaidea.asdoc{   
       
    import flash.display.Sprite;   
    import flash.events.Event;   
       
    /**  
    * 当创建一个ASDocExample实例的时候调度init事件。  
    * @eventType mx.events.FlexEvent.BUTTON_DOWN  
    */  
    [Event(name="init", type="flash.events.Event")]   
    /**  
     * ASDoc演示类。此例演示了如何写注释才能创建一个基本的AS项目的API文档。  
     * @example  
     * <listing version="3.0">  
     * var eg:ASDocExample=new ASDocExample();  
     * eg.print("ASDoc演示类");  
     * eg.test("flashlizi");  
     * </listing>  
     * @see http://www.riaidea.com  
     */  
  
    public class ASDocExample extends Sprite {   
           
        /**  
         * 实例的创建者。  
         * @default flashlizi  
         */  
        public var creator:String;   
        private var _date:Date;   
        /**  
         * 构造函数-constructor。  
         */  
        public function ASDocExample() {   
            this.creator = "flashlizi";   
            this._date = new Date();   
            dispatchEvent(new Event(Event.INIT));   
        }   
        /**  
         *    打印参数指定内容。  
         * @param    content 要打印的内容。  
         */  
        public function print(content:String):void {   
            trace(content);   
        }   
        /**  
         * 测试类的创建者是否与参数指定名称相同。  
         * @param    name 测试指定的名称。  
         * @return    创建者与指定名称相同返回true，否则返回false。  
         */  
        public function test(name:String):Boolean {   
            return name == creator;   
        }   
        /**  
         * 实例的创建时间。  
         */  
        public function get date():Date {   
            return date || new Date();   
        }   
        public function set date(value:Date):void {   
            _date = value;   
        }   
    }   
} 

现在来说明一下如果写类的注释才能创建一个比较完善的API文档。

1）首先，只有包含在/**与*/之间的注释才能被asdoc识别。对一个类的方法或者属性做注释，只要在之前加上这样的注释就可以了。
2）注释的第一行开始（不包括注释标记）是被注释对象（方法、属性等）的说明介绍。当出现@param 这样的注释标记的时候，asdoc就会自动解析为相应的内容。
3）本例ASDocExample中包含了一些常用的asdoc标记：
a、eventType。只能用于注释Event元标记，如[Event(name="init", type="flash.events.Event")]。这样在API文档中这个事件会出现这个类的Event说明块中。
b、example。用于创建一个示例。示例代码需写在< listing >和< /listing >之间。
c、see。用于创建“另请参见”说明块。
d、default。用于创建属性的“默认值”说明。
e、param。用于创建对方法的参数的说明。
f、return。用于创建对方法的返回值的说明。
g、private。使用此标记的方法或属性将不会输出到API文档中。

更多的asdoc标记请参看：http://livedocs.adobe.com/flex/3/html/help.html?content=asdoc_6.html#186140

下载本例的所有源文件： ASDocExample

------------------------------------------------______________________________

使用asDoc生成自己的Flex API Document

在FlexBuilder3中自带了asDoc(Doc生成工具). asDoc.exe的位置在..\Flex Builder 3 Plug-in\sdks\3.0.0\bin下 

使用FlexBuilder3中的External Tools 运行asdoc.exe,具体配置如下:
1.点击eclise工具按钮中的 open External Tools Dialog...

2.右键点击Program 新建


3.配置asDoc路径,源代码路径,以及生成时所需要的参数.

4.点击Apply然后Run就可以在你项目中的src目录下生成 blueonlyDocs的文件夹,里面就是所生成的doc,这样就大功告成了.
需要注意的是:
1.如果你的注释中包括中文,或者其他的非英文的语言,你需要在Common中设置它的编码格式UTF8:

2.如果您的代码中引用了AIR所需的类或者接口,生成的过程会报错,你需要在参数中添加AIR的swc路径,官方的方法是:
..\bin\asdoc -doc-sources C:\myApplication\myComponents\MyAirComboBox.as -library-path+=..\frameworks\libs\air -main-title "My AIR API Documentation" -window-title "My AIR API Documentation" -output air-asdoc
This command assumes the following:

• You run the command from the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\asdoc in your Flex Builder installation directory structure. If you are using the Flex SDK, or have installed Flex Builder on another operating system, modify the paths in this command as necessary.
• The AIR SWC files are installed in the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\frameworks\libs\air. This is the default directory location for a Flex Builder installation. This command uses the library-path option to the ASDoc tool to specify the directory location of the AIR SWC files. The"+=" operator to the -library-path option specifies to append the AIR SWC files to the Flex SWC files.
• The ASDoc tool writes the output to the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\asdoc\air-asdoc.

但是我怎么试也不好用,如果哪位高手会的话请告诉我,我的方法是直接把..\frameworks\libs\air 下的所有文件copy到..\frameworks\libs中,这样不用添加任何参数就可以编译运行.
好了,今天就写这么多了,祝您好运,以下附上我自己生成的Doc:

 

运用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一样使用同样的命令构造文件。

原文：http://www.blueidea.com/tech/multimedia/2008/6134.asp