记录 Node.js 项目
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/6096649/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Documenting Node.js projects
提问by Morten Siebuhr
I'm currently using JSDoc Toolkitto document my code, but it doesn't quite fit - namely, it seem to struggle with describing namespaces properly. Say you have two simple classes in each their files:
我目前正在使用JSDoc Toolkit来记录我的代码，但它不太适合 - 也就是说，它似乎难以正确描述命名空间。假设您的每个文件中有两个简单的类：
lib/database/foo.js:
lib/database/foo.js：
/** @class */
function Foo(...) {...}
/** @function ... */
Foo.prototype.init(..., cb) { return cb(null, ...); };
module.exports = foo;
And then something inherited lib/database/bar.js:
然后继承了一些东西lib/database/bar.js：
var Foo = require('./foo');
/**
* @class
* @augments Foo
*/
function Bar(....) {...}
util.inherits(Bar, Foo);
Bar.prototype.moreInit(..., cb) { return cb(null, ...); };
In the generated documentation, this is output simply as Fooand Bar, without the leading database(or lib.database), which are quite necessary when you don't have everything in a global scope.
在生成的文档中，这只是作为Fooand输出Bar，没有前导database（或lib.database），当您没有全局范围内的所有内容时，这是非常必要的。
I've tried throwing @namespace databaseand @name database.Fooat it, but it doesn't turn out nice.
我试着投掷@namespace database和@name database.Foo它，但它并没有变成好的。
Any ideas for making JSDoc output something more suitable, or some entirely different tool that works better with Node.js? (I looked briefly at Natural Docs, JSDuck and breezed over quite a few others that looked quite obsolete...)
任何让 JSDoc 输出更合适的东西的想法，或者一些与 Node.js 更好地工作的完全不同的工具？（我简要地看了看 Natural Docs、JSDuck 并轻而易举地浏览了很多其他看起来已经过时的东西......）
采纳答案by Morten Siebuhr
NOTE: Doxno longer outputs HTML, but a blob of JSON describing the parsed code. This means the code below doesn't work terribly well any more...
注意：Dox不再输出 HTML，而是一个描述解析代码的 JSON 块。这意味着下面的代码不再能很好地工作......
We ended up using Doxfor now. It is a lot like docco, that Raynos mentions, but thows all of it in one bit HTML-file for output.
我们现在最终使用了Dox。它很像Raynos提到的 docco ，但将所有内容都放在一位 HTML 文件中以供输出。
We hacked this into our makefiles:
我们把它黑进了我们的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" $^ > $@
It is not the prettiest or most efficient documentation ever made (and dox has quite a few minor bugs) - but I find it work rather well, at least for minor projects.
它不是有史以来最漂亮或最有效的文档（并且 dox 有很多小错误） - 但我发现它工作得很好，至少对于小项目来说。
回答by Raynos
JSDoc is a port of JavaDoc. So basically the documentation assumes classical OOP and that's not suited to JavaScript.
JSDoc 是 JavaDoc 的一个端口。所以基本上文档假设经典的 OOP 并且不适合 JavaScript。
Personally I would recommend using doccoto annotate your source code. Examples of it can be found for underscore, backbone, docco.
我个人建议使用docco来注释您的源代码。可以在underscore、backbone、docco 中找到它的示例。
A good alternative to docco is groc
docco 的一个很好的替代品是groc
As for an actual API documentation, I personally find auto generated documentation from comments just does not work for JavaScript and recommend you hand-write your API documentation.
至于实际的 API 文档，我个人认为从注释中自动生成的文档不适用于 JavaScript，建议您手写 API 文档。
Examples would be underscore API, Express API, nodejs API, socket.io docs
例如下划线 API、Express API、nodejs API、socket.io 文档
Similar StackOverFlow questions
类似的 StackOverFlow 问题
回答by Bill Gao
YUIDocis a Node.js application that generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen. YUIDoc provides:
YUIDoc是一个 Node.js 应用程序，它从源代码中的注释生成 API 文档，使用类似于 Javadoc 和 Doxygen 等工具的语法。YUIDoc 提供：
- Live previews. YUIDoc includes a standalone doc server, making it trivial to preview your docs as you write.
- Modern markup. YUIDoc's generated documentation is an attractive, functional web application with real URLs and graceful fallbacks for spiders and other agents that can't run JavaScript.
- Wide language support. YUIDoc was originally designed for the YUI project, but it is not tied to any particular library or programming language. You can use it with any language that supports /* */ comment blocks.
- 实时预览。YUIDoc 包括一个独立的文档服务器，使您在编写时预览文档变得微不足道。
- 现代标记。YUIDoc 生成的文档是一个有吸引力的、功能强大的 Web 应用程序，具有真实的 URL 和针对蜘蛛和其他无法运行 JavaScript 的代理的优雅回退。
- 广泛的语言支持。YUIDoc 最初是为 YUI 项目设计的，但它不依赖于任何特定的库或编程语言。您可以将它与任何支持 /* */ 注释块的语言一起使用。
回答by John Freeman
Sorry, I was not on StackExchange a year ago, but I believe the answer to your original question is to use the @memberOf tag:
抱歉，一年前我不在 StackExchange 上，但我相信您原来问题的答案是使用 @memberOf 标签：
/** @namespace */
database = {};
/**
* @class
* @memberOf database
*/
function Foo() { ... };
http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf
http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf
This tag may or may not have existed when you asked your question.
当您提出问题时，此标签可能存在，也可能不存在。
回答by Phil
Found a really nice solution for the problem: doxx.
为这个问题找到了一个非常好的解决方案：doxx。
It uses dox as mentioned above and converts this to nice HTML afterwards. Has a nice usage and worked great for me.
它使用上面提到的 dox，然后将其转换为漂亮的 HTML。有很好的用法，对我很有用。
回答by alejo8591
I work with JSDoc and is very efficient, in addition to easy, but when projects have many alternate libraries are quite complicated development. I found Groca very good tool based on Doccoand works with other languages like: Python, Ruby, C + +, among others...
我和JSDoc一起工作，效率很高，除了容易，但是当项目有很多备用库的时候开发还是挺复杂的。我发现Groc是一个非常好的工具，它基于Docco其他语言并可以与其他语言一起使用，例如：Python、Ruby、C++ 等……
Furthermore Grocworking with Markdown in GitHub which can be much more efficient when working with git as version control. Further helps assemble pages for publishing on GitHub.
此外Groc，在 GitHub 中使用 Markdown，在使用 git 作为版本控制时效率更高。进一步帮助组装页面以在 GitHub 上发布。
You can also use the task manager GruntJSthrough grunt-grocexample:
您还可以GruntJS通过grunt-groc示例使用任务管理器：
Install package:
安装包：
npm install grunt-groc --save-dev
npm install grunt-groc --save-dev
configure in your task file:
在你的任务文件中配置：
grunt.loadNpmTasks('grunt-groc');
grunt.loadNpmTasks('grunt-groc');
And the config task:
和配置任务：
// Project configuration.
grunt.initConfig({
groc: {
coffeescript: [
"coffee/*.coffee", "README.md"
],
options: {
"out": "doc/"
}
}
});
});
For run task:
对于运行任务：
grunt.registerTask('doc', ['groc'])
grunt.registerTask('doc', ['groc'])
