JsDoc Toolkit 简介

红薯 发布于 2009/10/16 14:49
阅读 2K+
收藏 5

JsDoc Toolkit 是一款辅助工具,你只需要根据约定在 JavaScript 代码中添加相应的注释,它就可以根据这些注释来自动生成API文档。对Java 熟悉的人可能会发现它和 Java 的文档自动化工具 JavaDoc 很像,没错,JsDoc Toolkit 就是基于 JavaDoc 开发的。

1. 历史

当你在Google中搜索 JsDoc 的时候,会发现两个项目主页,一个是 sourceforge 上的 JsDoc,另外一个是 google code 上的 JsDoc Toolkit。 这两个项目有什么关系呢?答案是:它们都是一个叫做Michael Mathews 的人开发的。大家可以在 JsDoc Toolkit wiki 里的 FAQ 中找到答案,这里我简要说明一下:

2001年的时候 JsDoc 项目发布,不过当时只是在 Michael 所在的公司内部使用,并没有开源。当时 JsDoc 是用 Perl 开发的(需要安装 Perl 环境,而且需要一个叫做 HTML::Template 的 Perl 模块),一年之后这个项目开源并放到了 sourceforge 上,之后被开发者 Gabriel Reid 接手并维护。 2006 年的时候 Michael 发现 JsDoc 的底层架构有点跟不上 JavaScript 的发展,于是决定重写,Gabriel Reid 和其它一些开发者也参与了这次重写。这次重写是用 Java 编写的,并改名为现在的 JsDoc Toolkit 。

2. 用法

由于 JsDoc Toolkit 是用 Java 编写的,所以运行的时候需要 Java 环境,请尽量使用比较新的JDK 和 JRE 。下面以 Linux 为例,说一下 JsDoc Toolkit 的用法。

首先,去 JsDoc Toolkit 的官方主页下载最新的压缩包(目前版本是2.3.2 ,点此下载),解压之后进入 jsdoc-toolkit 目录(即 jsrun.jar 所在的目录),然后运行下面的命令:

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

如果成功的话,你就会看到当前文件夹里多出了一个叫做 out 的文件夹,生成的文档就在里面了!然后你就可以在浏览器中查看了。如果你想了解 JsDoc Toolkit 的高级用法,可以用下面的命令:

1
java -jar jsrun.jar app/run.js --help

然后就可以看到一些参数说明,这里简单介绍几个:

-a 或者 –allfunctions :为全部函数生成文档,包括那些没有写注释的。
-c 或者 –conf :使用配置文件
-d= 或者 –directory=:指定生成文档的输出目录,默认是 “out”
-e= 或者 –encoding=:指定编码方式
-n 或者 –nocode :忽略所有代码,只为有 @name 标签的注释生成文档。
-o= 或者 –out= : 将日志信息输出到指定文件
-q 或者 –quiet : 不输出任何信息,包括警告。
-t= 或者 –template= :指定文档的模板,这个参数必须提供。

3. 标签简介

这里的标签是指约定的注释标签,只有写了这些标签, JsDoc Toolkit 才能根据这些标签来生成正确的文档,比如在 @example 之后跟一段小的代码例子。

JsDoc Toolkit wiki 有很详细的关于标签的参考,可以从这里开始

刚开始学习的时候可以粗略先看一遍所有的标签,然后在用到的时候再具体去查看相应标签的说明。

4. 与 Ant 结合

学习 JAVA 的人对于 Ant 这个自动化构建工具应该很熟悉,JsDoc toolkit 也有一个相应的 Ant 插件:JsDoc Toolkit Ant Task 。而且如果熟悉 Ant 的话,可以把JavaScript 的压缩、文档生成和发布都是用 Ant 来做,这个我还刚开始学习,就不写了,等以后熟悉了再总结一下。

加载中
0
pursuepxy
pursuepxy
好东西,学习了
返回顶部
顶部