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？（我简要地看了一下自然文档，JSDuck并且轻松地看了很多其他看起来相当过时的文章......）

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问题

Generating Javascript documentation

Answer 2

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

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

Answer 3

注意：Dox不再输出HTML，而是一小段JSON描述解析的代码。这意味着下面的代码不再适用了......

我们现在最终使用Dox。它与docco非常相似，Raynos提到，但是它只是在一个HTML文件中输出。

我们将其归入makefile s：

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

记录Node.js项目

6 个答案: