Documenting JavaScript – jGrouseDoc

Over the years, I’ve spent a lot of time searching for (and even creating) tools that do automatic documentation of JavaScript. As anyone familiar with this issue can attest to, it’s not an easy problem to solve, and the tools available seem to yield mediocre results at best.

There is, however, a new entry into the field that I’ve been using for month or so now, and that I find myself pleasantly surprised by. The tool is jGrouseDoc (jGD), by Denis Riabtchik. Unlike it’s predecessors, jGD starts with the premise that attempting to parse JavaScript source code is a futile endeavor. The language is not designed to express the high-level concepts and patterns that engineers strive to emulate (and document) in their design.

Instead, the tool looks exlcusively at the information in the comments you author, and provides a rich set of tags for you to annotate your comments with information about the logical structure. This requires a bit more typing, but frees the author and the tool from the shackles of having to figure out how to bolt documentation into the source in awkward ways.

For anyone familiar with JavaDoc, you’ll find the syntax easy to pick up. Here’s what it looks like ..

/**
 * Similar to Prototype's Template object, except the template is a DOM
 * element instead of a string.
 *
 * @class DomTemplate
 */

/** Hash of template id to DomTemplate objects
 * @variable {static Object} _byId
 */

/**
 * Get a dom template by name.  The returned template is cached, so
 * subsequent calls (for the same template) are efficient.
 *
 * @function {static DomTemplate} getTemplate
 * @param {String} id element id
 */

/**
 * Get a DOM element to use for doing DOM manipulations
 *
 * @function {private Element} _getHelper
 */

/**
 * Use DomTemplate.getTemplate()
 *
 * @constructor {private} initialize
 */

/**
 * Similar to evaluate(), except returns a DOM element. Note that for bulk
 * operations, it's more efficient to use evaluate() to create the HTML
 * string and then apply that using innerHTML.
 *
 * @function {Element} evaluateElement
 * @param {Object} data key-value pairs for token replacement
 */