ant结合jsdoc构建js文档—ant入门指南（8）

ant结合jsdoc构建js文档—ant入门指南（8）

上一篇教程明河演示了如何使用ant自动压缩文件，今天讲解ant如何ant结合jsdoc构建js文档。
JsDoc Toolkit 是一个将抽离js代码中的注释形成文档的程序，利用ant，你可以自动化打包js文档，需要用到的工具是jsdoc-toolkit-ant-task。调用的过程其实非常简单，整个过程类似ant调用yui-compressor。
下面的代码中，明河通过构建kissy-form库（明河和其他同事一起写的form组件集，目前还在编码阶段）的文档，演示jsdoc的用法。

1.准备

假设你已经下载了jsdoc-toolkit-ant-task，且保证你的js代码风格符合jsdoc要求，比如下面的代码：

<span style="font-family:Microsoft YaHei;">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() {
}
});</span>

详尽的jsdoc语法说明，请看jsdoc的wiki。

2.定义property

<span style="font-family:Microsoft YaHei;"><!--jsdoc-toolkit所在目录-->
<property name="jsdoc.dir" location="jsdoc-toolkit/"/>
<!--源代码目录-->
<property name="src.dir" location="../src/"/>
<!--文档输出目录-->
<property name="output.dir" location="../doc/"/></span>

请根据你本机的情况自行修改目录。

3.调用jsdoc

<target name="render">
    <taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"
             classpath="${jsdoc.dir}/jsdoc-toolkit-ant-task-1.1.2.jar;${jsdoc.dir}/java/classes/js.jar"></taskdef>
    <jsdoctoolkit template="jsdoc" jsdochome="${jsdoc.dir}/" outputdir="${output.dir}/" inputdir="${src.dir}"
                  encoding="utf-8">
    </jsdoctoolkit>
</target>

target目标下有二个任务：taskdef定义jsdockit的程序路径，jsdoctoolkit执行真正的构建任务。
接下来明河简单说明下其关键属性。

属性	说明
template	文档模板
outputdir	文档输出路径
inputdir	js源码目录
encoding	输出文档页面编码，默认是utf-8
depth	程序遍历源码目录的深度，默认是10

完成的构建代码如下：

<project name="doc" default="render" basedir=".">
<!--jsdoc-toolkit所在目录-->
<property name="jsdoc.dir" location="jsdoc-toolkit/"/>
<!--源代码目录-->
<property name="src.dir" location="../src/"/>
<!--文档输出目录-->
<property name="output.dir" location="../doc/"/>
<target name="render">
    <taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"
             classpath="${jsdoc.dir}/jsdoc-toolkit-ant-task-1.1.2.jar;${jsdoc.dir}/java/classes/js.jar"></taskdef>
    <jsdoctoolkit template="jsdoc" jsdochome="${jsdoc.dir}/" outputdir="${output.dir}/" inputdir="${src.dir}"
                  encoding="utf-8">
    </jsdoctoolkit>
</target>
</project>

下面是明河构建成功后目录情况：

有机会再给大家讲解常用的jsdoc语法。

注：targetdef用于使用第三方任务。见http://blog.163.com/yang_jianli/blog/static/161990006201272455531446/

转自：http://www.36ria.com/4816