In an effort to create better documentation, we've introduced inline documentation to our JavaScript at the office.

Since we use Dean Edwards' Base library for our inheritance the JSDoc out of the box wouldn't work without commenting explicit method name and memberOf attribute - which, in my view, defeats the point.

Here's how to get it working.

Thankfully the JSDoc project has been picked up (correct me if I'm wrong) and how supported entirely in JavaScript (via Rhino) as the JsDoc ToolKit.

With a small change (or not depending on your code) to the extend method, all the documentation generates perfectly.

For example, this is how my object would be normally laid out and documented:

/**
 * @fileoverview Definition of cat
 * @author Remy Sharp (actually pinched from Dean Edwards)
 */

var Cat = Animal.extend({
  /**
   * @constructor
   * Cats like to meow when they're made
   */
  constructor: function () {
    this.base();
    this.say("Meow");
  }

  /**
   * Our cat only eats mice
   * @param {Mouse} food Food fed to the cat
   */
  eat: function (food) {
    if (food instanceof Mouse) this.base();
    else this.say("Yuk! I only eat mice.");
  }
});

Making the following changes sorts out the JsDoc Toolkit parser and allows everything to be documented (note the @scope goes between the left parentheses and the left brace):

/**
 * @namespace Cat
 */
var Cat = Animal.extend(/** @scope: Cat */{

Now running the JsDoc Toolkit with -a (Include all functions, even undocumented ones) and it will properly parse the methods in the Base object:

java -jar app/js.jar app/run.js -t=templates/sweet *.js

If you've got a lot of files, you can run this little bit of command line Perl to do the manual work for you - though I recommend you make a backup, because it'll change the files directly:

perl -pi -e 's?(.*) = (.*)\.extend\({?/**\n * \@namespace\n */\n$1 = $2.extend(/** \@scope $1 */{\n?' *.js

Of course you're going to compress and strip out the documentation before you even think about serving it up on your web app though ;-)