JSDocs for Base

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.

UK EVENTAttend ffconf.org 2024

The conference for people who are passionate about the web. 8 amazing speakers with real human interaction and content you can't just read in a blog post or watch on a tiktok!

£249+VAT - reserve your place today

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 ;-)

JSDocs for Base

Comments