63

我目前正在使用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, ...); };

在生成的文档中，这只是作为Fooand输出Bar，没有前导database（或lib.database），当您没有全局范围内的所有内容时，这是非常必要的。

我试过投掷@namespace database，@name database.Foo但结果并不好。

有什么想法可以让 JSDoc 输出更合适的东西，或者一些完全不同的工具可以更好地与 Node.js 配合使用吗？（我简要地查看了 Natural Docs、JSDuck 并轻而易举地浏览了其他一些看起来相当过时的东西......）

4

6 回答 6

71

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

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

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

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

例如下划线 API、Express API、nodejs API、socket.io 文档

类似的 StackOverFlow 问题

于 2011-05-23T11:45:09.563 回答
17

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

  • 实时预览。YUIDoc 包含一个独立的文档服务器，使您在编写时预览文档变得很简单。
  • 现代标记。YUIDoc 生成的文档是一个有吸引力的功能性 Web 应用程序，具有真实的 URL 和优雅的后备，用于无法运行 JavaScript 的蜘蛛和其他代理。
  • 广泛的语言支持。YUIDoc 最初是为 YUI 项目设计的，但它不依赖于任何特定的库或编程语言。您可以将它与任何支持 /* */ 注释块的语言一起使用。
于 2012-10-08T00:30:21.053 回答
12

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

我们现在最终使用了Dox。它很像Raynos提到的 docco ，但将所有这些都放在一个位 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 有很多小错误） - 但我发现它工作得很好，至少对于小项目来说是这样。

于 2011-08-09T11:47:48.950 回答
5

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

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

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

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

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

于 2012-03-13T15:53:48.847 回答
3

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

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

https://github.com/FGRibreau/doxx

于 2013-04-14T05:41:11.673 回答
2

我使用 JSDoc 并且非常高效，除了简单之外，但是当项目有许多备用库时，开发是相当复杂的。我发现Groc是一个非常好的工具，它基于DoccoPython、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'])

于 2014-03-26T04:57:03.737 回答