My way of documenting JavaScript code.

Documenting JavaScript.md

Goals:

• Have code documented in the code
• Automatically generate a documentation website/readme

JSDoc

The most wildly used standard for documenting JavaSCript is JSDoc.

JSDOC uses @tags in comment blocks that start with /**. So to specify a parameter which should be a string you do something like:

@param {string} someString - This string is absolutely important to do something

And with this you can annotate your code in a way that enables a parser to generate a documentation.

Document

Some code styles I am a supporter of are however a bit tricky to document with JSDoc. Here are my personal solutions.

Revealing Module Pattern

The problem here is to get things to have the right names. My solution is to create namespaces with an alias and explicitly name each method.

/**
 *  A module of sorts
 *  @module
 *  @alias moduleName
 */

var module = (function() {

  /**
   *  An object that gets handed around.
   *  @typedef {Object} moduleName#configObject
   *  @property {string} str - Some string
   */

  /**
   *  Initialize some things.
   *  @method moduleName#init
   *  @param {moduleName#configObject} config - The configuration
   */
  function initModule(config) {
    
  }

  return {
    init: initModule
  }

}())

Create HTML

Assuming you are using node it is really easy to get a HTML version of your documentation. Just get JSDoc and probably a pretty template, I suggest docdash.

npm install --save-dev jsdoc docdash live-server

I prefer to save these things in my local development dependencies rather than as a global tool. In this way each project can rely on its specific version of the dependency. And everyone developing the project will just have local dependencies installed and will not have to install global things.

Once you have those you can create a script in you packe.json. I would also suggest using a .jsdoc.json configuration file for JSDoc, docdash has an example.

"scripts": {
  "jsdoc": "./node_modules/.bin/jsdoc --configure docs/config/.jsdoc.json --verbose",
  "serve-docs": "./node_modules/.bin/live-server ./docs"
}

As you can see I also set up a local version of live-server to show the documentation in my primary browser.

Readme

Another nice thing to have is documentation in your readme. And as JSDoc can use a markdwon file as the 'home' for the documentation maybe some docs in that as well. jsdoc-to-markdown to the rescue. This handy tool will create a markdown version of your documentation and pass it into a template if you so which.

So create a template markdown with some general information and a place to put the documentation.

# Project

Is really cool and I have a lot to say about it.

{{>main}}

The {{>main}} part is where jsdoc2md will insert your documentation. You can also be more specific about what you want included. Read their documentation for that.

npm install jsdoc-to-markdown --save-dev

Now lets extend our scripts to:

"scripts": {
  "jsdoc": "./node_modules/.bin/jsdoc --configure docs/config/.jsdoc.json --verbose",
  "serve-docs": "./node_modules/.bin/live-server ./docs",
  "api-docs": "node_modules/.bin/jsdoc2md \"src/**/*.js\" --template docs/api-docs.md > docs/api.md",
  "docs": "npm run api-docs && npm run jsdoc"
}

So here I use a template in api-docs.md and render the finished markdown into api.md. And jsdoc2md should use all .js files in src/ and any subfolders. I also created a task that will first generate the markdown version of my documentation and then the html one with the markdwon page as the 'home'. The later is set up in the config file for JSDoc.

Now just run:

npm run docs

And we are good and documented.

What goes where?

Personally I prefer to put the publicly accessible API of whatever I am developing into the markdwon and everything into the html version. This way I have every last method documented and can look it up and people who want to use my code can just check out the readme.