JavaScript 文档生成工具

如果你看过 YUI 的 RAW 源码，会发现很多跟 javadoc 语法类似的注释。据说 (via) 是使用 JSDoc 这个工具。但我探索了一遍，发现 YUI 多出很多 tag, 比如 @namespace, @static 之类，那么我只好怀疑 YUI 做了改良。一开始，我也试着使用了一下 JSDoc，遗憾的是，除了缺少一些 tag 外，它还不支持未匿名函数内的文档生成。比如，有时候为了保证不产生额外的全局变量会这么写：

(function(){
/**
 * 注释
 * @tag
 */
....
})();

或者我所喜欢的 “module pattern”:

var module = function(){
    var private;
    return {
    /**
     * 注释
     * @tag
     */
    pub1: function(){},
    pub2: function(){},
    ...
    }
}();

在这种情况下，在匿名函数内，和在 return 区块内的注释，JSDoc 就，用北京话说，「葛屁」（音）了，就是不起作用了。遗憾的是我的水平尚未上升到改良 perl 脚本以能按我所需的程度，因此，我寻找的是下一个目标。

JsDoc Toolkit 是一个不错的选择，虽然名称跟 JSDoc 不太容易区分。相比之下，它是使用 JavaScript 来处理文档的（当然，得通过 rhino），而且支持我前面所列举的两种形式（单是这点，我就只能选择它了）。

两者在 tag 的处理方面有所不同，感觉 JSDoc 的全面一些，但缺乏某些关键的 tag，比如 JsDoc Toolkit 中的 @scope 就很好用。

至于如何安装使用，直接上官网看吧 :)。欢迎同我交流。

粗粗看了一下 jQuery，似乎它也是通过 rhino 来处理文档生成的，嗯，我也得钻研一下，hack 出符合我要求的工具了。