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

版权所有，转载请注明来源http://gogo1217.iteye.com，违者必究！

    之前在整理公司框架的时候，曾经为javascript写过一些注释，但没有合适的工具来生成doc文件。后来通过google以及自己试用，发现jsdoc-toolkit和ext-doc2个工具比较有意思。

ext-doc详见：js doc 工具推荐及使用（二）：ext-doc

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.

1.在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解压出来即可。

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

##工程根目录
project.dir=..
###依赖包
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

3.配置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>

4.在jssrc下编写demo.js,

仅仅示例 。使用的是jsdoc-toolkit中http://code.google.com/p/jsdoc-toolkit/wiki/CookBook的第一个示例代码。

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() {
	}
});

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

6.控制台信息

7.doc效果展示

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

本文中的实例工程打包下载：

http://dl.iteye.com/topics/download/80800fa7-e92a-3ca4-92fa-2d00506db169