Archive for février, 2008

Generating doc on javascript a la javadoc

Javascript is a very fine language but contrary to Java there isn’t any native documentation engine.
Some open source projects offer you ways to generate doc from javadoc like comment in your code :

  • JsDoc : It is a good perl generator for javascript doc but it impose upon user tgto follow a given way to write javascript because it tries to interpret some javascript instruction to generate documentation :
                       /**                    * Shape is an abstract base class. It is defined simply                    * to have something to inherit from for geometric                    * subclasses                    * @constructor                    */                    function Shape(color){                      this.color = color;                    }                    // Bind the Shape_getColor method to the Shape class                    Shape.prototype.getColor = Shape_getColor;                    /**                     * Get the name of the color for this shape                     * @returns A color string for this shape                     */                    function Shape_getColor(){                      return this.color;                    }                    /**                     * Circle is a subclass of Shape                     */                    function Circle(radius){                      this.radius = radius;                    }                    /**                     * A very rough value for pi                     */                    Circle.PI = 3.14;                    /**                     * Get the radius of this circle                     * @returns The radius of this circle                     */                    function Circle_getRadius(){                      return this.radius;                    }                    // Circle is a subclass of Shape                    Circle.prototype = new Shape(null); 
  • JGrouse : It is much better when you want to use frameworks, because it allows documenting of Javascript classes, regardless which approach or framework is being used for it – be it Prototype, Dojo, Dean Edward’s Base, jGrouse or any other. And it is fully integrated as ant Task :
    exemple using dojo
                       dojo.provide("net.demay.geometry.Shape");                   /**                    * Shape is an abstract base class. It is defined simply                    * to have something to inherit from for geometric                    * subclassesl                    * @class net.demay.geometry.Shape                    * @author Vincent Demay                    */                   dojo.declare("net.demay.geometry.Shape", null, {                    /**                     * Color of the shape                     * @variable {net.demay.color.Color} color                    color : null,                    /**                     * @constructor Shape                     * @param {net.demay.color.Color} color                     */                    constructor: function(color){                      this.color = color;                    },                    /**                     * Get the name of the color for this shape                     * @function {net.demay.color.Color} return a color string for this shape                     */                    getColor: function(){                      return this.color;                    }                  }                   dojo.provide("net.demay.geometry.Circle");                   /**                    * A circle is a specific {@link net.demay.geometry.Shape                    * @class net.demay.geometry.Circle                    * @author Vincent Demay                    * @extends net.demay.geometry.Shape                    */                   dojo.declare("net.demay.geometry.Circle", [net.demay.geometry.Shape], {                    /**                     * Circle radius                     * @variable {Float} radius                     */                    radius :  null,                    //private no doc                    PI : 3.14,                    /**                     * @constructor Circle                     * @param {Float} radius                     */                    constructor: function(radius){                      this.radius = radius;                    },                    /**                     * Get the radius of this circle                     * @function {Float} getRadius                     */                    getRadius : function(){                      return this.radius;                    }                  }