为你的ActionScript项目创建API文档
2008-04-22 11:16
323 查看
作为一个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
下面以一个实际的示例来说明如何创建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
相关文章推荐
- 为你的ActionScript项目创建API文档
- 通过beego快速创建一个Restful风格API项目及API文档自动化
- 通过beego快速创建一个Restful风格API项目及API文档自动化(转)
- 通过beego快速创建一个Restful风格API项目及API文档自动化 本文演示如何快速(一分钟内,不写一行代码)的根据数据库及表创建一个Restful风格的API项目,及提供便于在线测试API的界
- 通过beego快速创建一个Restful风格API项目及API文档自动化
- 你造么? REST API 文档还可以这样创建!
- gitlab通过api创建组、项目、成员
- SpringBoot项目使用Swagger生成api文档
- storm文档(5)----创建storm新项目
- Android Studio官方文档:如何创建你的第一个Android项目
- Java生成自己项目API文档
- 如何将一个项目导出成API文档
- 如何生成自己项目的API文档
- Activit最入门学习文档,从如何创建项目开始共20章,看完,任何Java项目集成无压力
- 使用ASP.NET Web API Help Pages 创建在线接口文档
- eclipse中javadoc给项目生成api文档
- 使用FlashBuilder4生成ActionScript的API文档(包括一个64位电脑会出现的错误)
- 通过Revit API创建一个族并载入到工程文档中
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api