FlashBulider开发中的ASDOC的使用。

在Flash开发中，尤其是多人协同开发中灵活使用ASDoc会让你自己以及别人更容易你写的方法、对象的含义及使用方法。在Flash Builder、Flex Builder以及Flash Develop中支持ASDoc功能，当你为一个对象设置了ASDoc后你可以在鼠标移到该对象上时看到此对象的ASDoc描述信息。
 
       在AS项目中设置ASDoc的方法是在对象声明语句上方添加 /** ASDoc */标签：
为对象添加ASDoc：

1. /** 总和*/
   
2. private var sum:Number

复制代码

为函数添加ASDoc：

1.         
   
2. /**
   
3. * 播放动画 
   
4. * 
   
5. */                
   
6. public function play():void{
   
7.         timer.start();
   
8. }

复制代码

在/**和*/字符包裹中的字都会被当做是ASDoc说明文字，你还可以使用一些特殊记号，以'@'符号开头，常用的有：
@author 编写者姓名
@param 函数的变量
@return 函数返回值

下面演示了一种在方法中使用特殊记号后的ASDoc显示：

1. /**
   
2. * 计算两个数字的和
   
3. * @param num1        第一个数字
   
4. * @param num2        第二个数字
   
5. * @return                 第一和第二个数字相加的结果
   
6. * 
   
7. */                
   
8. private function calculate( num1:Number, num2:Number ):Number
   
9. {
   
10.         return num1 + num2;
    
11. }

复制代码

 

当然，在ASDoc编写时我发现它还支持使用HTML标签：

1. /**  我勒个去<br>这货居然是湿父<p> */
   
2. private var wolegequ:String;

复制代码

在很多IDE中都提供了添加ASDoc的快捷方式，在Flash Builder中，我们通过顶部菜单中的Source ----> Add ASDoc Comment（快捷键Ctrl + Shift + D）来为一个对象创建ASDoc标签对。

当你编写了一个/** */的ASDoc标签对后它会自动匹配下一个被声明了的对象，如下代码：

1. /** 我的目标在哪里？ */
   
2. trace("我是来阻碍你的");
   
3. str = "目标不会是我";
   
4. var target:String = "其实我才是你要找的人";

复制代码

我们编写的ASDoc匹配的对象是target，当我们鼠标移到target变量上去时会出现说明文档窗口。

当然，ASDoc不仅仅支持用在AS工程中，在Flex工程中你也可以使用它。在<mx:Script>标签对(Flex3)或者<fxeclarations>标签对(Flex4)中你可以使用和AS工程一样的语法来创建ASDoc：

1.     <fx:Script>
   
2.         <![CDATA[
   
3.             import flash.events.MouseEvent;
   
4. 
   
5.             /** 
   
6.              * 规则和AS工程一样
   
7.              *
   
8.              * @param eventObj The event object.
   
9.              */
   
10.             public function handleClickEvent(eventObj:MouseEvent):void {
    
11.                 dispatchEvent(eventObj);
    
12.             }   
    
13.             
    
14.             /** 
    
15.              * 看什么看？没见过SB啊？
    
16.              */
    
17.             public var myString:String = new String();
    
18.             
    
19.         ]]>
    
20.     </fx:Script>

复制代码

那么如果要为一个MXML标签添加ASDoc应该怎么办呢？你可以在MXML标签上写<!---   -->标签对来替代AS中的/** */标签对，注意喽，感叹号后面跟有3个横线哦~如果少了一根线将会被认作是注释。不过对于MXML标签来说一般只对设置有ID的组件才能匹配上ASDoc：

1.     <!--- 
   
2.         可以正确地匹配，当你鼠标移到id，即myButton上时会出现ASDoc说明窗口
   
3.      --> 
   
4.     <mx:Button id="myButton" label="This button has a comment"/>
   
5. 
   
6.     <!--- 
   
7.         无法匹配，ASDoc被忽略
   
8.      --> 
   
9.     <mx:Button label="This button has no id"/>

复制代码

但是对于一个自定义组件来说就没有这种限制, 下面是我自定义的一个名字叫做myCanvas的组件

1. <?xml version="1.0" encoding="utf-8"?>
   
2. <!---  我叫卖肯玩死  -->
   
3. <mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml">
   
4. 
   
5. </mx:Canvas

复制代码

之后在外面使用它，当鼠标悬停在此组件上时会出现ASDoc说明窗口：
 

       充分运用ASDoc功能会让你的代码更具可读性和重用性，别人会爱上使用你写出的类，COME ON, BABY, 我们没有理由拒绝之！

 

ASDoc是adobe官方提供的ActionScript的API文档生成工具，类似于java中的 javadoc，可以很放方便的生成api文档，对团队开发有很大帮助，现在已经集成在FlexBuilder3和flashBuilder4中。

1.运用ASDoc工具

1）打开 : 开始菜单—>所有程序—>Adobe—>Adobe Flex 3 SDK Command Prompt（命令提示符）

开始菜单—>所有程序—>Adobe—>Adobe Flash Builder 4 Plug-in SDK 命令提示符，根据你安装的路径以及flex的版本，路径会有不同。

2）会进入cmd命令行界面 （如果此时提示缺少msvcr71.dll文件，请下载此文件解压后然后放到C:WindowsSystem32下），用cd命令进入到要生成文档的工程目录下。当前目录是flex的安装目录，如果工程目录不与安装目录同盘符，直接输入盘符号，如d: ，然后回车，然后用cd到工程目录下。

3）使用ASDoc命令生成文档，可以使用的命令如下：

asdoc工具可用的命令行选项

asdoc工具工作的方式与mxmlc编译器工作的方式一样，他们采取同样的命令行选项。想知道更多关于mxmlc的信息，请参阅Flex的编译器。

下表列出了asdoc工具特有的命令行选项:

OptionDescription-doc-classes path-element [...]A list of classes to document. These classes must be in the source path. This is the default option.

This option works the same way as does the -include-classes option for the compc component compiler. For more information, see Using compc, the component compiler.

-doc-namespaces uri manifestA list of URIs whose classes should be documented. The classes must be in the source path.

You must include a URI and the location of the manifest file that defines the contents of this namespace.

This option works the same way as does the -include-namespaces option for the compc component compiler. For more information, seeUsing compc, the component compiler.

-doc-sources path-element [...]A list of files that should be documented. If a directory name is in the list, it is recursively searched.

This option works the same way as does the -include-sources option for the compc component compiler. For more information, seeUsing compc, the component compiler.

-exclude-classes stringA list of classes that should not be documented. You must specify individual class names. Alternatively, if the ASDoc comment for the class contains the @private tag, is not documented.-exclude-dependencies true|falseWhether all dependencies found by the compiler are documented. Iftrue, the dependencies of the input classes are not documented.

The default value is false.

-footer stringThe text that appears at the bottom of the HTML pages in the output documentation.-left-frameset-width intAn integer that changes the width of the left frameset of the documentation. You can change this size to accommodate the length of your package names.

The default value is 210 pixels.

-main-title “string”The text that appears at the top of the HTML pages in the output documentation.

The default value is “API Documentation“.

-output stringThe output directory for the generated documentation. The default value is “asdoc-output“.-package name “description”The descriptions to use when describing a package in the documentation. You can specify more than one package option.

The following example adds two package descriptions to the output:

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 stringThe path to the ASDoc template directory. The default is the asdoc/templates directory in the ASDoc installation directory. This directory contains all the HTML, CSS, XSL, and image files used for generating the output.-window-title “string”The text that appears in the browser window in the output documentation.

The default value is “API Documentation“.

The asdoc command also recognizes the following options from the compc component compiler:

asdoc命令也能识别下面这些来自compc组件编译器的命令行：

-source-path

-library-path

-namespace

-load-config

-actionscript-file-encoding

-help

-advanced

-benchmark

-strict

-warnings

示例：D:workbranchesvideoClientStudioStandaloneLivePlayer>asdoc -source-path src -doc-sources src -define=CONFIG::debug,true -define=CONFIG::release,false -library-path srcviewswc

2）Flash Builder4 beta – 导出ASDoc文档

这是来自Peter Elst’s Blog的一篇 文章，原文地址在：http://www.peterelst.com/blog/2009/06/08/flash-builder-4-beta-exporting-asdoc-documentation/

作者认为，虽然Flash Builder 4 beta增强了对ASDoc的支持，但它看起来还是没有提供一个简单的方式来导出HTML，所以如果要在Flash Builder 4 beta中实现这个功能，你需要使用扩展工具配置（external tool configuration）。

ASDoc是用于将你的项目代码中的注释提取出来并按照类，变量，方法等形式组织起来的一个帮助文档，可以导出为HTML格式，如果你的桌面上正好有一个 AS3的语法手册，那就很容易理解ASDoc导出的格式是怎样的。

下面的步骤介绍了如何在Flash Builder 4 Beta中使用ASDoc功能：

1. 选择菜单栏的 Run > External Tools > External Tools Configurations
2. 选择 Program (在左侧) 并且点击 New 按钮创建一个新的配置
3. 新配置命名为 “ASDoc”
4. 选择文件目录到“/Applications/Adobe Flash Builder Beta/sdks/4.0.0/bin/asdoc” (苹果系统) ，Windows系统默认的是 “你的程序安装路径Adobe Flash Builder Betasdks4.0.0binasdoc.exe”
5. 设置“Working Directory” 为 ${project_loc}, 这是一个变量，指向你当前的项目
6. 设置以下的参数，含义是默认的源码目录是src:-source-path src-doc-sources src

配置完成后，应该是如下图所示的样子：

要运行ASDoc并把文档导出到HTML，请选择菜单中的 Run > External Tools > ASDoc，当输出完成后，你可以在项目目录下的“asdoc-output”中找到导出的文档。

3）用Flash Develop生成AS文档

Flash Develop是Flash Builder的免费替代品。虽然它没有包含Flash Builder的全部特性，但是它有一个小 巧的AS文档生成器。按照以下步骤进行学习，你会十分容易掌握AS文档生成器。
什么是AS文档生成器？
就是为你的代码生成API文档。一个成功的例子就是Adobe Livedocs API。AS文档生成器会根据你的变量、函数和注释生成文档页面。
什么是Flash Develop？
一个在进行Flex和ActionScript开发时用到的免费轻巧的集成开发环境。它不包含调试器， 但大多数版本都有分析器。
为什么要创建AS文档？
向任何可能阅读你代码的人提供说明文档。对于重复使用的组件或类库特别有用。其他使用你代码的人不再会咒骂你的 名字或者频频向你求救。
创建AS文档
本文假定你已经配置了Flash Develop并且调用了Flex SDK。打开Flash Develop，选择 Tools –> Flash Tools–> Documentation Generator。弹出以下图片：

你马上会发现AS2被选定为默认的编译器。如果你仍然使用AS2编程，那么你确实应该寻求 帮助。现在我们把编译器改为AS3。添加页面标题，通常与你的工程名相同，再设置一个输出路径，通常与src路径同一级别。点击右上角的help获取更多 设置细节。
现在你的工程页面应该如下所示:

下面我们要把应用程序连接到AS3 livedocs生成器。点击设置标签，添加包含Flex SDK的bin路径。
别忘了点击“Save Settings”！

你已经准备妥当，生成时间与你的工程大小有关。确认已经点击了保存工程，把它保存至你的工程文件夹。如果你在关闭窗口前没有保存，工程标签页的东西 都会丢失。
点击这里可以查看结果http://www.blackcj.com/blog/wp-content/swfs/docs/

相关的一些资料：
ASDoc生成ActionScript的API类文档——命令参数
Running the ASDoc tool
用Flash Develop生成AS文档
ASDocs with Flash Develop
Flash Builder4 beta – 导出ASDoc文档

ASDoc生成actionscript的API文档