The Best Documentation Generator for Node
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
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:
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:
The doc will appear in
./out (default directory).
The default theme of JSDoc isn’t attractive. Fortunately there is docstrap.
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Then this is how you generate:
And that’s how you have a much better looking website.
The last command is long and tedious. Let’ use Grunt to improve and automate the process.
Then install the plugin Grunt-Jsdoc:
Configure the Gruntfile and use accordingly. This is mine after configuring:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
Now, you can simple run
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.