Generating documentation. JSDoc toolkit.

For some time now, I’ve been watching for the possibility of generating CAAT’s documentation automatically, but been unable to.
It’s not been until today, that after some deeply look at my own code and some tweaks that i’ve produced CAAT’s first automatic documentation. And it looks neat.

In CAAT everything tries to be object oriented. At first instance I got some code from Kevin Roast’s http://www.kevs3d.co.uk/dev/canvask3d/scripts/mathlib.js. That helped me a lot to understand some concepts on javascript functions and based all my inheritance strategy from that code. So thank’s Kevin.

But it was the use of this inheritance strategy which was preventing me from getting that pursued automatic documentation. The class definition was performed like this:


(function() {

  // Constructor
  CAAT.class1= function() {
  };

  // Class definition
  extend( CAAT.class1, CAAT.baseclass, {
    <
      put here your overriden and new
      methods/attributes definition/implementation
    >
  });

})();

So, what really happeded, was:

  1. that JSDoc toolkit won’t document anything contained inside the call to extend method.
  2. contrary to what I expected, a comment out of the block (function() {})() will be totally ignored.
  3. I moved the class description comment above the constructor block previously mentioned, but the documentation still was not created. I got only the class definition comment.

Many problems, with very simple solution.
First of all, I’ve changed the implicit extend function to a not so nice (or yet cooler, it depends who will read this) way. The extend method, contains no overrides anymore, and these overrides are substituted by the class prototype definition:


(function() {

  // Constructor
  CAAT.class1= function() {
  };

  CAAT.class1.prototype= {
    <
      Overrides and new attributes/methods definition.
    >
  }

  // Class extension
  extend( CAAT.class1, CAAT.baseclass );

})();

Rearrange the clases that way implied besides changing every class signature to conform to that syntax, refurbishing the implementation of the class method. A risky operation since the extend function is the core of class inheritance in CAAT. I’m proud to inform that javascript is an incredibly powerful languaje, so making that core change did not imply any impact on the rest of the code.
So by changing the extend function call, and defining the prototype that way, comments for every method should have bene created, but unfortunately that is not the case yet.
So as well as it’s nice for Closure Compiler to annotate your code with hints regarding type safety and function description it is for JSDoc toolkit as well. So by including the following annotations in the class definition comment, surprisingly for me comments started to be shown.

@constructor

Include also the following:
@extends CAAT.ActorContainer
and the inheritance information for the class definition will be shown as well, so in the end, the class definition loos like this:


(function() {
  /**
   * Class description. Yes, it is above the expected constructor class.
   * @constructor
   * @extends CAAT.baseclass
   */
  CAAT.class1= function() {
  };

  CAAT.class1.prototype= {
  ...
  }

  // Class extension, complement the prototype and
     define superclass/constructor attributes.
  extend( CAAT.class1, CAAT.baseclass );
})();

Some more annotations that will enrich your sourcecode comments will be:

  • @private to mark method as private in the documentation.
  • @protected to mark method as protected in the documentation.
  • @param {type} to describe a method parameter. The type part is optional and will
    help determining what type the parameter is. Closure compiler will take care of this type.

  • etc.
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s