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.

Book nowModern Universal React with Next.js

Stop worrying about configuration, and complex codebases: Next.js makes SSR with React easy. Book your masterclass 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 ;-)

Want more?

Posts, web development learnings & insights, exclusive workshop and training discounts and more, direct to your inbox.

I won't send you any spam, and you can unsubscribe at any time. Powered by ConvertKit