Ant+JSDocTookit生成Javascript文档

需要备上下面三样东西

JSDocTookit

<a href="http://code.google.com/p/jsdoc-toolkit/">http://code.google.com/p/jsdoc-toolkit/</a>

JSDocTookit Ant Task

<a href="http://code.google.com/p/jsdoc-toolkit-ant-task/">http://code.google.com/p/jsdoc-toolkit-ant-task/</a>

Rhino

<a href="http://www.mozilla.org/rhino/">http://www.mozilla.org/rhino/</a>

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

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

&lt;jsdoctoolkit jsdochome="${jsdoctoolkit.home}" template="jsdoc" outputdir="./docs" encoding="utf-8"&gt;

如果有中文指定输入/输出文件的编码encoding="utf-8"

<a href="http://code.google.com/p/jsdoc-toolkit-ant-task/">jsdoctoolkit ant task的详细属性</a>

关于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下面。

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

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

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

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

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

把所有.js文件都转成不带BOM的UTF-8编码

修改文件/bin/yuidoc_highlight.py：

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

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