HTML5 Dev Gal

Messing with HTML5, CSS3 and JavaScript.

Finally Got JSdocs Working With My Node App

| Comments

Man was that a pain in the butt! Read on for my adventures in javascript API documentation.

JSDoc

I wanted to create API documentation for my app so I took a look at jsdoc.

Docco

For some reason which I don’t remember, I wound up getting sidetracked with docco but by the time I got there I had already created jsdoc formatted dockblocks which don’t play well with docco.

Dox

So I read about dox which is supposed to allow you to use jsdoc formatted dockblocks to generate docco type documentation. Being a huge fan of grunt automation I figured I’d use the grunt-dox plugin

That was a total cluster so I gave up.

My Solution

I finaly crawled back to jsdoc and came up with this psuedo automated solution.

Node JSDoc Toolkit Module

I installed node-jsdoc-toolkit:

npm install jsdoc-toolkit --save-dev

Configuration

Then I created a config file and put it in the jsdoc-toolkit node module conf directory, ie:

$APP_DIR/node_modules/jsdoc-toolkit/conf/thisconffile.conf

Here’s an example of what my configuration file, which I named looks jsdoc.conf, looks like:

Automate With Shell Script

Then to automate running the jsdoc command with the conf file I created a super simple shell script. Please note its referring to my configuration file named jsdoc.conf. Replace that with the name of your configuration file.

I placed this shell script in my application directory.

Grunt-ify Shell Script

Then to grunt-ify this shell script I installed grunt-shell

npm install grunt-shell --save-dev
Gruntfile.js Configuration

If your not used to using grunt or configuring grunt tasks, you might want to check out the Grunt Getting Started guide.

For information on the specific grunt-shell options, take a look at the documentation.

For my purposes I set up the Gruntfile.js grunt-shell options like this:

shell: {
  docs : {
    command: './docs.sh'
  }
}

I added the shell task to my grunt test task so when I run

grunt test

in the console my documentation gets created.

Windows

I have a co-worker running a Windows 7 PC who I wanted to be able to update docs. I couldn’t figure out how to do this using the node js-toolkit module or grunt-shell.

I had to dowload the jsdoc-toolkit source and create a batch file.

Here’s the batch file I created:

To run this you need to:

  • Have JRE. If you don’t have it, download it here
  • Be able to run java command in a command prompt. For this you’ll need to:
    • Set your JAVA_HOME environment variable (I’ve got .;C:\Program Files (x86)\Java\jre7 as the value)
    • Add ;%JAVA_HOME%\bin to the PATH environment variable. More details on this can be found here

As usual I’m sure there’s a much better way to do this but this is what worked for me after hours of pain.

Comments