js doc工具推荐及使用（一）：jsdoc-toolkit

        在项目开发过程中，需要合适的工具来生成doc文件，通过google以及试用，发现jsdoc-toolkit和ext-doc2个工具比较有意思。

        下面详细介绍下jsdoc-toolkit在实际工程中的应用

        官方地址为：http://code.google.com/p/jsdoc-toolkit/

        相关注释标签为：http://code.google.com/p/jsdoc-toolkit/w/list

        jsdoc-tookit解压后分为4个目录，6个文件。其中templates目录为doc html的模板，如有兴趣和需要可以对模板进行修改和定制。

        为了能在ant脚本中使用jsdoc-toolkit,还需要额外的2个包：

        jsdoc-toolkit-ant-task.jar，下载地址为：http://code.google.com/p/jsdoc-toolkit-ant-task/;

        js.jar，下载地址为：https://developer.mozilla.org/en/Rhino_downloads_archive.

一.在eclipse中新建工程如图所示：

其中：

        build目录为ant脚本（build-doc.xml），配置文件（build.properties），将ant的变量改为外部应用，以便替换和更改。

        doc为jsdoc将来生成doc文件的目录。

        jssrc为js源代码文件的存放目录类似于java的源代码文件存放目录为src。

        lib为工程中将要使用的额外的jar包，其中build为编译环境所依赖的，有别于运行环境所依赖的包。

        在lib中存在着jsdoc-toolkit解压后的文件以及jsdoc-toolkit-ant任务扩展包，以及mozilla旗下的js包，下载后将zip包中的js.jar解压出来即可。

 

二.配置build.properties如下所示：

##\u5de5\u7a0b\u6839\u76ee\u5f55
project.dir=..

##\u4f9d\u8d56\u5305
lib.dir = ${project.dir}/lib
lib.build.jsdoc= ${lib.dir}/build/jsdoc-toolkit-ant-task-1.1.2.jar
lib.build.js=${lib.dir}/build/js.jar
jsdoc.home=${lib.dir}/build/jsdoc_toolkit-2.4.0/

doc.dir=${project.dir}/doc
src.dir=${project.dir}/jssrc

 

三.配置build-doc.xml如下所示：

<?xml version="1.0" encoding="UTF-8"?>

<project name="test" default="jsdoc">
	<description>test</description>
	<!--导入配置文件 -->
	<property file="build.properties" />

	<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit">
		<classpath>
			<pathelement location="${lib.build.jsdoc}" />
			<pathelement location="${lib.build.js}" />
		</classpath>
	</taskdef>

	<tstamp>
		<format property="build.time" pattern="yyyy-MM-dd-HH-mm" />
	</tstamp>
	<!-- ================================= target: init ================================= -->
	<target name="init">
		<tstamp />
		<delete dir="output" />
	</target>

	<!-- ================================= target: doc ================================= -->
	<target name="jsdoc" depends="init">
		<jsdoctoolkit jsdochome="${jsdoc.home}" template="jsdoc"
			outputdir="${doc.dir}" inputdir="${src.dir}" />
	</target>
</project>

 

四.在jssrc下编写demo.js、demo2.js

        仅仅示例,demo.js使用的是jsdoc-toolkit中http://code.google.com/p/jsdoc-toolkit/wiki/CookBook的第一个示例代码,demo2.js是基于demo.js上稍加修改的。

demo.js

var MyClass = Class.create(
/** @lends MyClass# */
{
	/**
	 * Description of constructor.
	 * @class Description of class.
	 * @constructs
	 */
	initialize : function(arg0, arg1) {
		//...
	},
	/** A method. */
	myFunc : function() {
	},
	/** An instance field. */
	myVar : 123
});

// ... and if you want to add class fields ...

Object.extend(MyClass,
/** @lends MyClass */
{
	/** A class method. */
	classFunc : function() {
	}
});

demo2.js

var MyClass2 = Class.create(
/** @lends MyClass2# */
{
	/**
	 * Description of constructor.
	 * @class Description of class.
	 * @constructs
	 */
	initialize : function(arg0, arg1) {
		//...
	},
	/** A method. */
	myFunc2 : function() {
	},
	/** An instance field. */
	myVar : 123
});

// ... and if you want to add class fields ...

Object.extend(MyClass2,
/** @lends MyClass2 */
{
	/** A class method. */
	classFunc2 : function() {
	}
});

 

五.在build-doc.xml右键，在弹出的菜单中选择"Run As"->"Ant Build"

六.控制台信息

 

七.doc效果展示

        总结：jsdoc-toolkit是一款简单、容易上手的javascript api生成工具。支持是现在流行的多种js oop编写方式，详见http://code.google.com/p/jsdoc-toolkit/wiki/CookBook。

 

文章来源：http://gogo1217.iteye.com