Documenting Node js projects

Question

I'm presently documenting my code with JSDoc Toolkit, but it's not quite right - in particular, it seems to struggle with accurately specifying namespaces. Let's say each of their files contains two simple classes:

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, ...); };

This is displayed simply as Foo and Bar in the generated documentation, without the leading database (or lib.database), which is required when you don't have everything in a global scope.

I've tried both the @namespace and @name databases.

It's a waste of time, but it doesn't turn out well.

Any suggestions for improving JSDoc's output or finding a new tool that works better with Node.js? (I skimmed over Natural Docs and JSDuck, as well as a few others that appeared to be out of date...)

Answer 1

JSDoc is a JavaDoc port. As a result, the documentation assumes traditional OOP, which is incompatible with JavaScript.

Personally, I would suggest annotating your source code with docco. Underscore, backbone, and docco are all examples of it.

Groc is a decent alternative to docco.

In terms of actual API documentation, I personally believe that auto-generated documentation based on comments does not work well with JavaScript and that you should create your API documentation by hand.

Underscore API, Express API, nodejs API, and socket.io documentation are other examples.

To know more about Node JS, It's recommended to join Node JS Certification today.