记录Node.js项目

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来注释你的源代码.它的例子可以在下划线,骨干,docco中找到.

docco的一个很好的替代品是杂货

至于实际的API文档,我个人发现自己生成的注释文档不适用于JavaScript,建议您手工编写API文档.

示例可以是下划线API,Express API,nodejs API,socket.io文档

类似的StackOverFlow问题

• 生成Javascript文档

Answer 2

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

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

Answer 3

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

我们现在最终使用Dox.这很像docco,Raynos提到,但是所有这些都在一个HTML文件中输出.

我们把它砍成了我们makefile的:

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

当您提出问题时,此标记可能存在也可能不存在.