Thursday 14 February 2008
Generating doc on javascript a la javadoc
Par Vincent DEMAY, Thursday 14 February 2008 :: Javascript
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 dojodojo.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; } }
Power by