记录Node.js项目

Question

我目前正在使用JSDoc Toolkit来记录我的代码，但它似乎并不完全适用于描述命名空间。假设你有两个简单的类，分别在它们各自的文件中：

lib/database/foo.js:

/** @class */
function Foo(...) {...}

/** @function ... */
Foo.prototype.init(..., cb) { return cb(null, ...); };

module.exports = foo;

然后某些东西继承了 lib/database/bar.js：

var Foo = require('./foo');

/**
 * @class
 * @augments Foo
 */
function Bar(....) {...}

util.inherits(Bar, Foo);

Bar.prototype.moreInit(..., cb) { return cb(null, ...); };

在生成的文档中，这些内容仅以Foo和Bar输出，而没有前面的database或lib.database，但是当你不把所有内容都放在全局范围内时，这些前缀是非常必要的。

我已经尝试使用@namespace database和@name database.Foo，但效果不太好。

有什么想法可以让JSDoc输出更合适的内容，或者是否有其他完全不同的工具能更好地与Node.js配合使用？（我简要查看了Natural Docs、JSDuck和很多其他看起来相当过时的工具...）

- Morten Siebuhr

Answer 1

JSDoc是JavaDoc的移植版。因此，文档假定使用经典OOP，而这不适合于JavaScript。

个人建议使用docco来注释源代码。它的示例可以在underscore、backbone、docco中找到。

一个很好的替代docco的工具是groc

至于实际的API文档，我个人认为通过注释自动生成文档在JavaScript中并不奏效，建议手写API文档。

例如：underscore API、Express API、nodejs API、socket.io docs

类似的StackOverFlow问题

• 生成JavaScript文档

- Raynos

---

Groc开箱即用，但有没有简单的方法来自定义模板？ - Mmmh mmh

“Express API”链接指向ExpressJS网站的github项目。这是有意为之吗？ - BillyTom

虽然它在使用Dojo Toolkit的JavaScript方面表现出色，但回答非常好！ - Tom

链接到underscore和backbone的页面未找到。 - DauleDK

Answer 2

YUIDoc是一个Node.js应用程序，它使用类似于Javadoc和Doxygen等工具的语法从源代码中的注释生成API文档。YUIDoc提供以下特性：

• 实时预览。YUIDoc包括一个独立的文档服务器，可以轻松地在编写文档时进行预览。
• 现代标记。YUIDoc生成的文档是一个具有真实URL和优雅回退功能的可吸引人、功能齐备的Web应用程序，适用于不能运行JavaScript的蜘蛛和其他代理。
• 广泛的语言支持。YUIDoc最初是为YUI项目设计的，但它不依赖于任何特定的库或编程语言。您可以将它与任何支持/* */注释块的语言一起使用。

- Bill Gao

Answer 3

注意：Dox不再输出HTML，而是输出描述解析代码的JSON数据块。这意味着下面的代码已经无法很好地工作了...

我们最终选择了Dox。它与Raynos提到的docco类似，但将所有内容都放在一个HTML文件中输出。

我们通过修改makefile来实现此功能：

JS_FILES := $(shell find lib/ -type f -name \*.js | grep -v 3rdparty)

#Add node_modules/*/bin/ to path:
#Ugly 'subst' hack: Check the Make Manual section 8.1 - Function Call Syntax
NPM_BINS:=$(subst bin node,bin:node,$(shell find node_modules/ -name bin -type d))
ifneq ($(NPM_BINS),) 
    PATH:=${NPM_BINS}:${PATH}
endif

.PHONY: doc lint test

doc: doc/index.html

doc/index.html: $(JS_FILES)
    @mkdir -p doc
    dox --title "Project Name" $^ > $@

这可能不是最漂亮或最高效的文档（而且dox有一些小bug）- 但我发现它对于小项目来说相当好用。

- Morten Siebuhr

---

DOX不再生成文档......它生成可以提供给模板的JSON。是否有这样一个模板的示例？ - Dave Dopson

很遗憾，我不知道有这样的内容。 - Morten Siebuhr

那么你如何使用它？XML输出并不完全“人类可消化”... - Dave Dopson

我们暂时停止使用它了。目前我们还没有找到其他符合我们需求的东西 - 我们希望在我们之前有人会急需制作能够解析JSON的模板。 ;) - Morten Siebuhr

我在 Github 上添加了一个问题来跟踪这个差距，并链接回这个线程...（https://github.com/visionmedia/dox/issues/38） - Dave Dopson

Answer 4

抱歉，我去年没有在StackExchange上，但我相信你原来问题的答案是使用@memberOf标签：

/** @namespace */
database = {};

/**
 * @class
 * @memberOf database
 */
function Foo() { ... };

http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf

这个标签在你提问时可能存在，也可能不存在。

- John Freeman

Answer 5

我找到了一个非常好的解决方案，叫做doxx。

它使用了之前提到的dox，并将其转换为漂亮的HTML格式。它的用法很棒，对我来说非常有效。

https://github.com/FGRibreau/doxx

- Phil

Answer 6

我使用JSDoc非常高效且易用，但是当项目有许多替代库时，开发就会变得相当复杂。我发现Groc是一个非常好的工具，基于Docco，并且可以与其他语言一起使用，如：Python、Ruby、C++等等...

此外，Groc在GitHub中使用Markdown，这在使用git作为版本控制时可以更加高效。它还可以帮助组装页面以发布到GitHub。

您还可以通过grunt-groc使用任务管理器GruntJS，例如：

安装包：

npm install grunt-groc --save-dev

在您的任务文件中进行配置：

grunt.loadNpmTasks('grunt-groc');

还有配置任务：

// Project configuration.
grunt.initConfig({
   groc: {
    coffeescript: [
       "coffee/*.coffee", "README.md"
   ],
    options: {
       "out": "doc/"
   }
 }

});

运行任务：

grunt.registerTask('doc', ['groc'])

- alejo8591