记录 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 并轻而易举地浏览了其他一些看起来相当过时的东西......）

Answer 1

JSDoc 是JavaDoc 的一个端口。所以基本上文档假定经典的 OOP 并且不适合 JavaScript。

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

docco 的一个很好的替代品是groc

至于实际的 API 文档，我个人发现 cmets 自动生成的文档不适用于 JavaScript，建议您手写 API 文档。

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

类似的 StackOverFlow 问题

• Generating Javascript documentation

Answer 2

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

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

Answer 3

注意：Dox 不再输出 HTML，而是描述已解析代码的 JSON 块。这意味着下面的代码不再工作得非常好......

我们现在最终使用Dox。它很像 Raynos 提到的 docco，但将其全部放在一个 HTML 文件中以供输出。

我们将其入侵到我们的makefiles：

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 有很多小错误） - 但我发现它工作得相当好，至少对于小项目来说是这样。

Answer 4

抱歉，一年前我不在 StackExchange，但我相信您最初问题的答案是使用 @memberOf 标签：

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

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

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

当您提出问题时，此标签可能存在也可能不存在。

Answer 5

为这个问题找到了一个非常好的解决方案：doxx。

它使用上面提到的 dox，然后将其转换为漂亮的 HTML。很好用，对我来说效果很好。

https://github.com/FGRibreau/doxx

Answer 6

我使用 JSDoc 并且非常高效，除了简单之外，但是当项目有许多备用库时，开发是相当复杂的。我发现Groc 是一个基于Docco 的非常好的工具，并且可以与其他语言一起使用，例如：Python、Ruby、C++ 等等……

此外，Groc 在 GitHub 中使用 Markdown，这在使用 git 作为版本控制时效率更高。进一步帮助组装页面以在 GitHub 上发布。

您还可以使用任务管理器GruntJS 到grunt-groc 示例：

安装包：

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'])