JsDoc Toolkit：JavaScript 文档利器

随着 Web2.0 的风靡，JavaScript 已经成为一门被人们重新认识的编程语言，由于大量 JS 开源框架的出现，利用 JavaScript 开发 的项目越来越多，越来越大。同时，也有越来越多JavaScript 开发问题暴露出来，如性能、网页加载速度等，其中，JavaScript 文档维护也成 为了开发者亟待解决的一个难题。

许多现代编程语言都有自己的集成化文档生成工具，像 Java 有 JavaDoc，.NET有 NDoc，PHP有 PHPDoc，这些自动化文档工具可以根据代码中的注释自动生成代码文档。

JsDoc Toolkit 就是这样一个自动化文档工具，它是发布在 Google code 上的一个开源项目，和其他语言的文档工具一样，它可以自动从 JavaScript 代码中提取注释生成格式化文档。

下载地址

http://code.google.com/p/jsdoc-toolkit/downloads/list

运行环境

JsDoc Toolkit是用Java开发的，运行时需要 Java 1.5+。

用法

在运行之前，你需要把当前的工作目录切换到JsDoc Toolkit目录，并确保将java.exe所在目录添加到环境变量中。

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc mycode.js

mycode.js是需要生成文档的js代码，如果mycode.js和JsDoc不在同一目录，请加上文件的绝对或者相对路径。如果项目中有多个js， 可以使用通配符*来指定多个js文件(*.js)。-e参数指定文档编码，-t参数指定文档模板位置（可以新建或修改模板文件让输出的代码文件更具特 色），生成的文档文件在JsDoc目录下的out目录中。为了使用方便，我写了一个批处理文件，你可以将代码保存为run.bat，放到JsDoc目录 下：

::run.bat

@echo off

::js文件名(换成你的js文件名)

set jsname=jquery.js

::js文件路径(换成你的js文件路径)

set jspath=C:/test/

echo start...

java -jar jsrun.jar app/run.js -a -e=GBK -t=templates/jsdoc "%jspath%%jsname%.js"

::out/%jsname%/index.html

echo finished.

pause

常用关键字

author	标识代码作者
class	标识该函数是一个类的构造函数
constant	声明常量
constructor	同class
default	默认值
deprecated	声明已弃用的对象
description	对象描述
event	事件函数
example	例子代码
fileOverview	Javascript文件总体描述
ignore	忽略有这个标记的函数
link	与其他JsDoc对象关联
name	显示声明JsDoc不能自动检测的对象
namespace	声明命名空间
param	参数
private	声明私有对象
property	显式声明一个属性
public	声明公开对象
requires	声明所依赖的对象或文件
returns	返回值
see	声明可参考的其它对象
since	声明对象从指定版本开始生效
static	显式声明一个静态对象
throws	声明函数执行过程中可能抛出的异常
type	声明变量类型或者函数返回值类型
version	版本号

详细语法请参阅：JsDoc Toolkit Wiki

整理自：http://blog.tugai.net/2010/01/08/jsdoc-toolkit-usage/

本文是使用 B3log Solo 从 简约设计の艺术 进行同步发布的

原文地址：http://88250.b3log.org/articles/2010/11/26/jsdoc-toolkit-usage.html