jsdoc toolkit - a jsdoc tool for Java developer

原始发表时间：2010-02-20

 

    早有耳闻jsdoc的大名，但是最近才下决心要把js代码文档化，因为想让一份js代码更好的为team所用，进一步发展，没有好的文档，几乎很难实现。

    首先得安装使用jsdoc工具的环境，在网上找到两篇文章“http://caterpillar.onlyfun.net/Gossip/AjaxGossip/InstallJSDoc.html ”和“http://jsdoc.sourceforge.net/#install ”，但按这两篇文章的说明，要安装Perl环境，接着用jsdoc的perl脚本来生成js代码的文档，总感觉十分别扭（毕竟一直在windows下用java开发，很少使用perl语言）。

    后来发现了Google早就有的jsdoc toolkit（这是个用java开发的生成jsdoc的jar工具包），下载链接是“http://code.google.com/p/jsdoc-toolkit/downloads/list ”，下载最新的2.3.3-beta版，将该zip包解压到目录“E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\”中，在该目录中有几个文件夹和文件，关键目录名有app和templates，关键的文件则有jsrun.jar和README.txt。

    首先阅读官方的文档README.txt中，其中“RUNNING VIA SHELL SCRIPT”的段落甚为有用，按照其说明编写命令行脚本如下：

    java -jar E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ jsrun.jar E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ app\run.js -t=E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ templates\jsdoc\ -p -r=4 -u E:\work_eclipse\workspace_JDK1.5\webim\ webcontent\js\

    执行环境是jdk1.6.x，jsdoc toolkit 2.3.3-beta

    从上面脚本的下划线文本中可以看出——应用项目为webim，其js存放在项目下的相对目录 webcontent\js 中，在命令行中执行该脚本，就会在目录 E:\software\develop\script\perl\jsdoc_toolkit-2.3.3-beta\jsdoc-toolkit\ out\jsdoc\ 中生成js代码的jsdoc文档——分别是两个文件（名为index.html、files.html）和一个目录（名为symbols），双击index.html就能看到对应js的文档了，格式跟javadoc非常相近。

    但是起初我遇到一个问题，就是所有的js类的方法都归到了_global_ 这个类下面，各个类名没有在Class Index中列举出来，后来查看了Google官方的TagReference（文章底部的附加资料中有相关链接），才知道是js代码中没有加入@class标记，导致jsdoc没有识别出来哪些是类代码的注释，加上@class后，再次生成jsdoc即可。

 

附加资料：

1. jsdoc toolkit 部分参数说明，可以参见《JsDoc Toolkit 简介》“http://www.zhuoqun.net/html/y2009/1363.html ”
   
2. js代码中jsdoc编写规范，可以查看链接“http://code.google.com/p/jsdoc-toolkit/wiki/TagReference ”