Ant+JSDocTookit生成Javascript文档

文章转自：hikejun.com/blog/?p=33

需要备上下面三样东西
JSDocTookit
http://code.google.com/p/jsdoc-toolkit/

JSDocTookit Ant Task
http://code.google.com/p/jsdoc-toolkit-ant-task/

Rhino
http://www.mozilla.org/rhino/

再项目的目录下建一个docs目录，编辑Build.xml：

<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"classpath="${jsdoctoolkit.home}jsdoctoolkit-0.4.jar;${rhino.home}js.jar"/>

<jsdoctoolkit jsdochome="${jsdoctoolkit.home}" template="jsdoc" outputdir="./docs" encoding="utf-8">

如果有中文指定输入/输出文件的编码encoding="utf-8"
jsdoc的模板文件就是HTML+CSS，所以可以修改成你想要的样子，也可以装上第三方的模板，见http://code.google.com/p/jsdoc-toolkit/wiki/TemplateGallery

jsdoctoolkit ant task的详细属性

关于JSDoc的简单用法：
由于生成的文档页面默认是UTF-8的，所以源文件应该也是UTF-8编码的。

基中一些最常用的标签：
/**
* @fileoverview 对这个js文件介绍一下
* @author Kejun 维护人的联系方式
* @version 0.0.1 版本
*/
生成之后这段将出现在"File Index"里。

定义类：
/**
个人信息类
@class
*/
var myConfig = {
name: "Kejun",
title: "Web Developer",

/**
显示我的名字
@function say
*/
say: function(){
alert("我叫" + this.name);
}
};
定义构造器：
/**
* 一个人物的基类
* @constructor
*/
function Person(name, title){
this.name = name;
this.title = title;
}

/**
@namespace myApp包括我的一些应用
*/
YAHOO.CN.myApp = {};
myConfig, Person, YAHOO.CN.myApp将会出现在“Classes”列表中。

另外常用的对Function的描述：
/**
* 显示某人的年龄
* @function
* @param {string} sName 名字
* @param {number | sring} nAge 年龄
*/

属性定义
/**
我的名字
@type string
*/
这些将出现在对应的Class/Namespace/Constructor或Global下面。

参考更多JSDoc的所有标签

你还可以使用下面的方法安装：

文章来自：dancewithnet.com/2008/12/30/why-start-yui-doc/

YUI Team实践出了一个高效易协作的前端代码开发流程：代码首先由Ant来组织管理和版本化、接着由JsLint来验证，然后由YUI Doc文档化、最后由YUI Compressor进行压缩发布。上个月初，YUI Team公布了这个新的JavaScript API文档生成工具YUI Doc，它本来专门为YUI提供API级别的文档的，现在它开源为人民服务了。

YUI Doc和JavaDoc、JSDoc和JsDoc Toolkit相似。YUI Doc是由注解驱动（comment-driven ）的系统，它通过解析代码中描述结构的注解来生成文档。由于它纯粹的依赖于注解，所以并不像一些模拟系统一样需要有惯用语和代码模式。更详细的介绍可以看YUI Doc的官方文档和YUI blog上的《YUI Doc: A New Tool for Generating JavaScript API Documentation》（由于YUI blog咱们无法访问，比较好的解决方案就是在Google Reader中订阅它的Feed，直接输入 http://yuiblog.com即可。）

YUI Doc是基于Python开发，且依赖几个扩展库，加之其Getting Started写的也比较含糊，所以如何使用这个工具反而成为第一道门槛，尤其对于那些对Python不熟悉的同学来说。所以，下面的重点是介绍如何在Windows上使用YUI Doc：

1. 下载Python2.5.2安装之。
   虽然Python3.0和Python2.6都已经出来很久了，但之所以依旧选择Python2.5.2，是因为后面要用到的安装Python扩展库的工具setuptools在Windows下的最新版本对应的是Python2.5。我不知道它是否支持2.5以上，有兴趣的可以试试。
2. 下载setuptools-0.6c9.win32-py2.5.exe并安装之，setuptools会自动安装到Python所在安装目录的Scripts目录下。
   setuptools为Python提供了简单的包管理和发行功能。后面的扩展库的安装就是利用它的easy_install，非常方便。有兴趣的可以看看《可爱的 Python: 使用 setuptools 孵化 Python egg》。
3. 为了使用方便需要配置一下“环境变量”，即在“我的电脑 》右键 》属性 》高级 》环境变量 》系统变量 》 选中Path 》 编辑”，在弹出框中加入：

   ;D:\Program Files\python;D:\Program Files\python\Scripts

   然后应用即可。前面的两个路径分别是我的Python和setuptools的安装路径，你需要修改成你自己的。

4. 开始 》运行 》(Win + R)输入“cmd”，输入：

   python -c "import pkg_resources"

   没有任何输出，即表示setuptools安装成功。接着依次输入运行：

   easy_install Pygments
   easy_install simplejson
   easy_install Cheetah
   

   setuptools会自动寻找并下载Pygments、SimpleJSON和Cheetah这三个扩展库，并安装它。

5. 下载最新版本YUI Doc，并解压在某个目录下。复制其bin目录下的example.bat文件，重命名为test.bat，然后用记事本或其他编辑器打开并配置它:

   SET yuidoc_home="D:\yui\yuidoc"
   REM YUI Doc的路径
   SET parser_in="D:\yui\src"
   REM 要生成文档的JS文件路径，比如为了测试就我临时建一个，里面就放着YUI 的 dom.js
   SET parser_out="D:\yui\src\parser"
   REM YUI Doc会把解析的JS文件提取出来所要存放的位置
   SET generator_out="D:\yui\src\generator"
   REM 生成文档存放的位置
   

   保存并运行test.bat后，就会发现D:\yui\src中多了parser和generator两个目录，而generator中正是你要的文档。

支持中文注释的解决方案

1. 下载最新版本YUI Doc，解决方案在yuidoc-27中验证通过
2. 把所有.js文件都转成不带BOM的UTF-8编码
3. 修改文件/bin/yuidoc_highlight.py：

   from pygments.formatters import HtmlFormatter
   #新增下行
   import codecs
   ...
   #f=open(os.path.join(path, file))
   #fileStr=StringIO(f.read()).getvalue()
   #f.close()
   fileStr = codecs.open( os.path.join(path, file), "r", "utf-8" ).read()
   log.info("highlighting " + file)
   
   #highlighted = highlightString(fileStr)
   highlighted = highlightString(unicode(fileStr))
   

4. 在Python的\Lib\site-packages\下增加一个名为sitecustomize.py的文件，其内容为：

   import sys
   sys.setdefaultencoding('utf-8')
   

谢谢小马提供中文注释的解决方案

学会使用工具仅仅是开始了一小步，仔细看看YUI Doc的官方文档吧，利用其来促使我们写出更高效优雅的前端代码并惠及更多的人才是一大步。