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

发布于，归属于前端开发工具。 前3个座位已被强势霸占！ 共有120人围观    

上一篇教程明河演示了如何使用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要求，比如下面的代码：

  1. var MyClass = Class.create( 
  2. /** @lends MyClass# */ 
  3. { 
  4.     /**
  5.      * Description of constructor.
  6.      * @class Description of class.
  7.      * @constructs
  8.      */ 
  9.     initialize : function(arg0, arg1) { 
  10.         //... 
  11.     }, 
  12.     /** A method. */ 
  13.     myFunc : function() { 
  14.     }, 
  15.     /** An instance field. */ 
  16.     myVar : 123 
  17. }); 
  18.  
  19. // ... and if you want to add class fields ... 
  20.  
  21. Object.extend(MyClass, 
  22. /** @lends MyClass */ 
  23. { 
  24.     /** A class method. */ 
  25.     classFunc : function() { 
  26.     } 
  27. });

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

2.定义property

  1. <!--jsdoc-toolkit所在目录-->
  2.     <property name="jsdoc.dir" location="jsdoc-toolkit/" />
  3.     <!--源代码目录-->
  4.     <property name="src.dir" location="../src/" />
  5.     <!--文档输出目录-->
  6.     <property name="output.dir" location="../doc/" />

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

3.调用jsdoc

  1. <target name="render">
  2.         <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>
  3.         <jsdoctoolkit template="jsdoc" jsdochome="${jsdoc.dir}/" outputdir="${output.dir}/" inputdir="${src.dir}" encoding="utf-8">
  4.  
  5.         </jsdoctoolkit>
  6.     </target>

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

属性

说明

template

文档模板

outputdir

文档输出路径

inputdir

js源码目录

encoding

输出文档页面编码，默认是utf-8

depth

程序遍历源码目录的深度，默认是10

完成的构建代码如下：

  1. <?xml version="1.0"?>
  2. <!--
  3. @author:剑平（明河）<minghe36@126.com>
  4. -->
  5. <project name="doc" default="render" basedir=".">
  6.     <!--jsdoc-toolkit所在目录-->
  7.     <property name="jsdoc.dir" location="jsdoc-toolkit/" />
  8.     <!--源代码目录-->
  9.     <property name="src.dir" location="../src/" />
  10.     <!--文档输出目录-->
  11.     <property name="output.dir" location="../doc/" />
  12.     <target name="render">
  13.         <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>
  14.         <jsdoctoolkit template="jsdoc" jsdochome="${jsdoc.dir}/" outputdir="${output.dir}/" inputdir="${src.dir}" encoding="utf-8">
  15.  
  16.         </jsdoctoolkit>
  17.     </target>
  18. </project>

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

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

（如果您喜欢这篇教程，可以通过支付宝打赏我们1元哦，拜谢！）

感谢阅读这篇文章，如果你遇到了问题，可以在文章底部留言，你可以通过以下方式联络到明河： 1、进入我的微博首页跟随我 2、我的email：minghe36@126.com

辛勤码教程中...求订阅...O(∩_∩)O

跟作者说两句

:wink: :twisted: :roll: :oops: :mrgreen: :lol: :idea: :evil: :cry: :arrow: :?: :-| :-x :-o :-P :-? :) :( :!: 8-O 8)

3个座位已被强势霸占！

  1. 很太吧

    2012年1月10号很太吧到此一游，站点样式不错

  2. 很太吧

    好雨知时节，看完这篇外面居然下起了大雨

  3. 36ria

    学习了，希望能够继续出jslint、csslint及单元测试（如jasmine或ant）方面的教程，让前端的开发路变成条康庄大道 :twisted:

同类