read

After researching on the various modules available, I find the best documentation generator is JSDoc, and also Docco.

Yea, you can use both simultaneously.

Why Both ?

JSDoc is regular API documentation that explain the methods and modules of your project. You annotate your source code with @param etc to explain them. It is good for public API documentation.

Docco is a 2 vertical layout documentation with prose and the code. It has recently became popular and a good example is underscore documentation. It is more suitable for explaining the flow of your code. It is good for small team, or ownself.

Docco is actually very simple. It parses your source code, and any comments that starts with // is the prose. You can use markdown too. And, it doesn’t consider /** comments */ as a prose, which is good, because JSDoc uses them.

I like to use both simultaneously because

• Docco is great for reading your source code with the comments right beside. It helps in explaining the flow.

• JSDoc is great for looking up on how to use a method, the parameters and type.

Setting up Docco is easy so I will not be explaining.

But ironically, the documentation from JSDoc is not the clearest of all.

Setting up JSDoc

There are 2 places for their documentation - usejsdoc.org and github.

Firstly, go to github to understand how to install the module.

I made a mistake to install the module globally with npm -g, which is WRONG. Install locally with:

npm install jsdoc

This is because you need to edit the config file in the module at ./node_modules/jsdoc/config.json. And this part of the information is at usejsdoc.org..

To generate, run this:

./node_modules/.bin/jsdoc yourJavaScriptFile.js

The doc will appear in ./out (default directory).

Using Docstrap

The default theme of JSDoc isn’t attractive. Fortunately there is docstrap.

I like amelia (retro feel) and cerulean (twitter like).

Again, the instructions wasn’t very clear.

To use docstrap, you have to npm install ink-docstrap, then edit config.json in jsdoc, and add the following to templates key. Note the theme used is cerulean below.

    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        },
        "systemName"      : "DocStrap",
        "footer"          : "",
        "copyright"       : "DocStrap Copyright © 2012-2013 The contributors to the JSDoc3 and DocStrap projects.",
        "navType"         : "vertical",
        "theme"           : "cerulean",
        "linenums"        : true,
        "collapseSymbols" : false,
        "inverseNav"      : true
    },

Then this is how you generate:

./node_modules/.bin/jsdoc yourJavaScriptFile.js -t ./node_modules/ink-docstrap/template -c ./node_modules/jsdoc/conf.json

And that’s how you have a much better looking website.

Using Grunt

The last command is long and tedious. Let’ use Grunt to improve and automate the process.

Install Grunt:

npm install -g grunt-cli

Then install the plugin Grunt-Jsdoc:

npm install grunt-jsdoc --save-dev

Configure the Gruntfile and use accordingly. This is mine after configuring:

module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    jsdoc : {
        dist : {
            src: ['./*.js'],
            jsdoc: './node_modules/.bin/jsdoc',
            options: {
                destination: 'doc',
                configure: './node_modules/jsdoc/conf.json',
                template: './node_modules/ink-docstrap/template'
            }
        }
    }
  });

  grunt.loadNpmTasks('grunt-jsdoc');

};

Now, you can simple run grunt jsdoc.

Others

There is a good review of Jsdoc vs Docco vs Yuidoc vs Doxx.

Dox is another good one, but it now no longer spits out html. It only spits out JSON, yet there is no good render template with it.

Smartcomments is helpful to generate @param etc, but it didn’t work well for me. Not a big deal missing it.

Lastly, manual handwritten wiki style is still great. It is good for tutorials such as Express documentation. You can write in markdown or HTML.