Documenting Node.js projects

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

score 72 · Answer 1 · edited May 23 '17 at 12:25

72

JSDoc is a port of JavaDoc. So basically the documentation assumes classical OOP and that's not suited to JavaScript.

Personally I would recommend using docco to annotate your source code. Examples of it can be found for underscore, backbone, docco.

A good alternative to docco is groc

As for an actual API documentation, I personally find auto generated documentation from comments just does not work for JavaScript and recommend you hand-write your API documentation.

Examples would be underscore API, Express API, nodejs API, socket.io docs

Similar StackOverFlow questions

Generating Javascript documentation

edited May 23 '17 at 12:25

Community

1
1

answered May 23 '11 at 11:45

Raynos

166,823
56
351
396

1

Groc works really well out of the box but is there any easy way to customize the template? – Mmmh mmh Jul 26 '14 at 17:29
The link "Express API" points to the github-project of the ExpressJS webseite. Is that on purpose? – BillyTom Jun 03 '16 at 11:24
Great answer although it does work nicely with javascript using the Dojo Toolkit! – Tom Oct 24 '16 at 01:32
1

Page not found on links to underscor and backbone. – DauleDK Nov 25 '16 at 06:01

score 17 · Answer 2 · edited Sep 23 '13 at 14:25

YUIDoc is a Node.js application that generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen. YUIDoc provides:

Live previews. YUIDoc includes a standalone doc server, making it trivial to preview your docs as you write.
Modern markup. YUIDoc's generated documentation is an attractive, functional web application with real URLs and graceful fallbacks for spiders and other agents that can't run JavaScript.
Wide language support. YUIDoc was originally designed for the YUI project, but it is not tied to any particular library or programming language. You can use it with any language that supports /* */ comment blocks.

score 12 · Accepted Answer · edited Dec 18 '14 at 14:59

12

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.

edited Dec 18 '14 at 14:59

Julian D.

5,464
1
25
35

answered Aug 09 '11 at 11:47

Morten Siebuhr

6,068
4
31
43

2

So DOX no longer spits out documentation...... it spits out JSON "which can be fed to a template". Is there an example of such a template? – Dave Dopson Nov 04 '11 at 02:06
None that I know of, unfortunately. – Morten Siebuhr Nov 04 '11 at 08:59
so how do you use it? The XML output isn't exactly "human consumable"... – Dave Dopson Nov 06 '11 at 22:23
We've stopped using it for now. And we haven't quite found anything else that matches our needs right now - we're hoping someone else will be desperate enough to produce the JSON-eating templates before we do. ;) – Morten Siebuhr Nov 07 '11 at 07:32
2

I added an issue to github tracking this gap and linking back to this thread... (https://github.com/visionmedia/dox/issues/38) – Dave Dopson Nov 07 '11 at 23:11

score 5 · Answer 4 · answered Mar 13 '12 at 15:53

Sorry, I was not on StackExchange a year ago, but I believe the answer to your original question is to use the @memberOf tag:

/** @namespace */
database = {};

/**
 * @class
 * @memberOf database
 */
function Foo() { ... };

http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf

This tag may or may not have existed when you asked your question.

score 3 · Answer 5 · answered Apr 14 '13 at 05:41

3

Found a really nice solution for the problem: doxx.

It uses dox as mentioned above and converts this to nice HTML afterwards. Has a nice usage and worked great for me.

https://github.com/FGRibreau/doxx

answered Apr 14 '13 at 05:41

Phil

3,282
1
20
16

alejo8591 · Answer 6 · 2014-03-26T05:05:40.093

I work with JSDoc and is very efficient, in addition to easy, but when projects have many alternate libraries are quite complicated development. I found Groc a very good tool based on Docco and works with other languages like: Python, Ruby, C + +, among others...

Furthermore Groc working with Markdown in GitHub which can be much more efficient when working with git as version control. Further helps assemble pages for publishing on GitHub.

You can also use the task manager GruntJS through grunt-groc example:

Install package:

npm install grunt-groc --save-dev

configure in your task file:

grunt.loadNpmTasks('grunt-groc');

And the config task:

// Project configuration.
grunt.initConfig({
   groc: {
    coffeescript: [
       "coffee/*.coffee", "README.md"
   ],
    options: {
       "out": "doc/"
   }
 }

});

For run task:

grunt.registerTask('doc', ['groc'])

Documenting Node.js projects

6 Answers6