Question

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;

And then something inherited 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 Foo and Bar, without the leading database (or lib.database), which are quite necessary when you don’t have everything in a global scope.

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

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

Answer 1

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…

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.

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" $^ > $@

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.