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

Since we use [Dean Edwards'](http://dean.edwards.name/) [Base](http://dean.edwards.name/weblog/2006/03/base/) library for our inheritance the [JSDoc](http://jsdoc.sourceforge.net/) 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.

[![](/images/terminal-600.jpg)](https://training.leftlogic.com/buy/terminal/cli2?coupon=BLOG\&utm_source=blog\&utm_medium=banner\&utm_campaign=remysharp-discount)

[READER DISCOUNTSave $50 on terminal.training](https://training.leftlogic.com/buy/terminal/cli2?coupon=BLOG\&utm_source=blog\&utm_medium=banner\&utm_campaign=remysharp-discount)

[I’ve published 38 videos for new developers, designers, UX, UI, product owners and anyone who needs to conquer the command line today.](https://training.leftlogic.com/buy/terminal/cli2?coupon=BLOG\&utm_source=blog\&utm_medium=banner\&utm_campaign=remysharp-discount)

[$49 - only from this link](https://training.leftlogic.com/buy/terminal/cli2?coupon=BLOG\&utm_source=blog\&utm_medium=banner\&utm_campaign=remysharp-discount)

Thankfully the JSDoc project has been picked up (correct me if I’m wrong) and how supported entirely in JavaScript (via [Rhino](http://www.mozilla.org/rhino/)) as the [JsDoc ToolKit](http://jsdoctoolkit.org/).

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](http://dean.edwards.name/packer/) and strip out the documentation before you even think about serving it up on your web app though ;-)

Published 8-Jan 2008 under #base & #code & #javascript & #jsdocs. [Edit this post](https://github.com/remy/remysharp.com/blob/main/public/blog/jsdocs-for-base.md)

Comments

Lock Thread

Login

Add Comment[M ↓   Markdown]()

[Upvotes]()[Newest]()[Oldest]()

?

Anonymous

-1 points

9 years ago

Hi!

I know this is a rather old post, but I’m triyng to do this exact same thing and I’m running into some problems.\ Namely, there’s no "@scope" variable anymore in jsDocs. Any thoughts as to how to do this at present-date?

Thanks!

[Commento](https://commento.io)