记录Node.js项目 [英] Documenting Node.js projects

问题描述

我目前正在使用 JSDoc Toolkit 来记录我的代码，但它没有不合适 - 就像正确地描述命名空间似乎很难。假设每个文件中有两个简单的类：

I'm currently using JSDoc Toolkit to 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:

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 ，没有领先的数据库（或 lib.database ），这是非常必要的，当你没有全局范围内的所有东西。

In the generated documentation, this is output simply as Foo and Bar, without the leading database (or lib.database), which are quite necessary when you don't have everything in a global scope.

我已经尝试投掷 @namespace数据库和 @name database.Foo ，但它并没有变得不错。

I've tried throwing @namespace database and @name database.Foo at it, but it doesn't turn out nice.

使JSDoc输出更合适的任何想法，或者与Node.js更好的一些完全不同的工具？ （我简要地看了自然文件，JSDuck，并对很多其他看起来相当过时的文章进行了微调...）

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...)

推荐答案

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

NOTE: Dox no 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 现在。这很像 docco ，Raynos提到，但是所有这一切都在一点点的HTML-文件输出。

We ended up using Dox for now. It is a lot like docco, that Raynos mentions, but thows all of it in one bit HTML-file for output.

我们将这个入侵到了我们的 makefile s：

We hacked this into our 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有很多次要的错误） - 但我发现它工作得很好，至少对于小项目。

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.

这篇关于记录Node.js项目的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！