I’m hoping this post might just help out at least one person that gets put into the same boat I was. I’ve focused back onto a different project at work, mainly working with JavaScript (JS) and DOJO. There may potentially be two other parties working on the same code base so I took the time yesterday to class out all the code. Generally, I always use jsdoc style commenting in my JS code. However, this was my first time utilizing the jsdoc-toolkit to generate docs from code with DOJO.
If you don’t do any sort of advanced utilization of DOJO, you may never experience any issues. I, however, found it to be a pain to get DOJO classes to show up properly in my docs.
Let’s use a simple class as an example…
dojo.declare("SnakeClass", null,
{
constructor: function(breed)
{
this._breed = breed;
},
GetBreed: function()
{
return this._breed;
},
SetMorph: function(morph)
{
this._morph = morph;
},
GetMorph: function()
{
return this._morph;
},
});
OK, here’s how I originally would have commented this code…
/**
* Represents a single snake.
* @author jbfreels
* @see Reptiles#
* @class
*/
dojo.declare("SnakeClass", null,
{
/**
* New snake
* @param breed The breed of snake.
* @constructor
*/
constructor: function(/**String*/ breed)
{
this._breed = breed;
this._morph = "normal";
},
/**
* @returns {String} Breed of the snake.
*/
GetBreed: function()
{
return this._breed;
},
/**
* Sets morph type of the snake.
* @param morph Morph type of snake.
*/
SetMorph: function(/**String*/ morph)
{
this._morph = morph;
},
/**
* @returns {String} Morph type of the snake.
*/
GetMorph: function()
{
return this._morph;
},
});
Here’s what jsdoc outputs…
This does no one any good. Let’s try and trick the jsdoc parser to think this is a valid class (since it kind of is).
dojo.declare("SnakeClass", null,
{
/** @lends SnakeClass# */
/**
* Snakes, snakes everywhere!
* @param breed The breed of snake.
* @class Represents a single snake.
* @author <a href="mailto:jb@tech-tiles.com">J.B. Freels</a>
* @see Reptiles#
* @constructs
*/
constructor: function(/**String*/ breed)
{
this._breed = breed;
this._morph = "normal";
},
/**
* Retrieve breed of the snake.
* @returns {String} Breed of the snake.
*/
GetBreed: function()
{
return this._breed;
},
/**
* Sets morph type of the snake.
* @param morph Morph type of snake.
*/
SetMorph: function(/**String*/ morph)
{
this._morph = morph;
},
/**
* Retrieve morph type of the snake.
* @returns {String} Morph type of the snake.
*/
GetMorph: function()
{
return this._morph;
},
});
And here’s what we get with jsdoc…
