Ant+JSDocTookit生成Javascript文档

需要备上下面三样东西
JSDocTookit
http://code.google.com/p/jsdoc-toolkit/

JSDocTookit Ant Task
http://code.google.com/p/jsdoc-toolkit-ant-task/

Rhino
http://www.mozilla.org/rhino/

 

build.xml

<?xml version="1.0" encoding="UTF-8"?>
<project name="name of project" default="jsdoc" basedir=".">
	<!--taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit" classpath="${basedir}/jsdoctoolkit-ant-task-1.0.2.jar;${jsdoctoolkit.home}jsrun.jar;${rhino.home}js.jar" />

	<target name="default" description="default">
		<jsdoctoolkit jsdochome="${jsdoctoolkit.home}" template="jsdoc" inputdir="./WebRoot" log="./1.log" outputdir="./docs" encoding="utf-8">
			<source file="edit-grid2.js"/>
		</jsdoctoolkit>
	</target-->

	<property name="jsdoctoolkit.home" value="D:/jsdoc_toolkit-2.3.2/jsdoc-toolkit" />
	<property name="rhino.home" value="D:/rhino1_7R2" />
	<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit">
		<classpath>
			<pathelement path="./jsdoctoolkit-ant-task-1.0.2.jar" />
			<pathelement path="${jsdoctoolkit.home}/jsdebug.jar" />
			<pathelement path="${jsdoctoolkit.home}/jsrun.jar" />
			<pathelement path="${rhino.home}/js.jar" />
		</classpath>
	</taskdef>
	<target name="jsdoc" description="Automatically create documentation for Javascript code." >
		<mkdir dir="./jsdoc/" />
		<jsdoctoolkit jsdochome="${jsdoctoolkit.home}" template="jsdoc" outputdir="${build.dir}/jsdoc/" includeprivate="true" includeunderscored="true" includeundocumented="true">
			<fileset dir="./WebRoot">
				<include name="**/*.js" />
			</fileset>
		</jsdoctoolkit>
	</target>
</project>

其中定义jstoolkit任务类型：

<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit" classpath=”${jsdoctoolkit.home}jsdoctoolkit-0.4.jar;${rhino.home}js.jar”/>

 

定义target执行

	<target name="jsdoc" description="Automatically create documentation for Javascript code." >
		<mkdir dir="./jsdoc/" />
		<jsdoctoolkit jsdochome="${jsdoctoolkit.home}" template="jsdoc" outputdir="${build.dir}/jsdoc/" includeprivate="true" includeunderscored="true" includeundocumented="true">
			<fileset dir="./WebRoot">
				<include name="**/*.js" />
			</fileset>
		</jsdoctoolkit>
	</target>

如果有中文指定输入/输出文件的编码encoding=”utf-8″
jsdoc的模板文件就是HTML+CSS，所以可以修改成你想要的样子，也可以装上第三方的模板，见http://code.google.com/p/jsdoc-toolkit/wiki/TemplateGallery

jsdoctoolkit ant task的详细属性

关于JSDoc的简单用法：
由于生成的文档页面默认是UTF-8的，所以源文件应该也是UTF-8编码的。

基中一些最常用的标签：

/**
* @fileoverview 对这个js文件介绍一下
* @author Kejun 维护人的联系方式
* @version 0.0.1 版本
*/
生成之后这段将出现在”File Index”里。


定义类：
/**
个人信息类
@class
*/
var myConfig = {
name: “Kejun”,
title: “Web Developer”,


/**
显示我的名字
@function say
*/
say: function(){
alert(”我叫” + this.name);
}
};


定义构造器：
/**
* 一个人物的基类
* @constructor
*/
function Person(name, title){
this.name = name;
this.title = title;
}


/**
@namespace myApp包括我的一些应用
*/
YAHOO.CN.myApp = {};
myConfig, Person, YAHOO.CN.myApp将会出现在“Classes”列表中。

另外常用的对Function的描述：
/**
* 显示某人的年龄
* @function
* @param {string} sName 名字
* @param {number | sring} nAge 年龄
*/


属性定义
/**
我的名字
@type string
*/