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