documentation - 记录 Node.js 项目

Question

关闭。这个问题是 opinion-based .它目前不接受答案。

---

想要改进这个问题吗？ 更新问题，以便 editing this post 提供事实和引用来回答它.

关闭 4 年前。

Improve this 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 文档，我个人发现从注释自动生成的文档不适用于 JavaScript，建议您手写 API 文档。

示例为 underscore API , Express API , nodejs API , socket.io docs

类似的 StackOverFlow 问题

• Generating Javascript documentation