/tags/jsdoc_toolkit-2.2.1/jsdoc-toolkit/app/test/jsdoc_test.js

  1/** 
  2 * @fileoverview This file is to be used for testing the JSDoc parser
  3 * It is not intended to be an example of good JavaScript OO-programming,
  4 * nor is it intended to fulfill any specific purpose apart from 
  5 * demonstrating the functionality of the 
  6 * <a href='http://sourceforge.net/projects/jsdoc'>JSDoc</a> parser
  7 *
  8 * @author Gabriel Reid gab_reid@users.sourceforge.net
  9 * @version 0.1 
 10 */
 11
 12
 13/**
 14 * Construct a new Shape object.
 15 * @class This is the basic Shape class.  
 16 * It can be considered an abstract class, even though no such thing
 17 * really existing in JavaScript
 18 * @constructor
 19 * @throws MemoryException if there is no more memory 
 20 * @throws GeneralShapeException rarely (if ever)
 21 * @return {Shape|Coordinate} A new shape.
 22 */
 23function Shape(){
 24  
 25   /**
 26    * This is an example of a function that is not given as a property
 27    * of a prototype, but instead it is assigned within a constructor.
 28    * For inner functions like this to be picked up by the parser, the
 29    * function that acts as a constructor <b>must</b> be denoted with
 30    * the <b>&#64;constructor</b> tag in its comment.
 31    * @type String
 32    */
 33   this.getClassName = function(){
 34      return "Shape";
 35   }
 36
 37   /** 
 38    * This is an inner method, just used here as an example
 39    * @since version 0.5
 40    * @author Sue Smart
 41    */
 42   function addReference(){
 43       // Do nothing...
 44   }
 45   
 46}
 47
 48/**
 49 * Create a new Hexagon instance.
 50 * @extends Shape
 51 * @class Hexagon is a class that is a <i>logical</i> sublcass of 
 52 * {@link Shape} (thanks to the <code>&#64;extends</code> tag), but in 
 53 * reality it is completely unrelated to Shape.
 54 * @param {int} sideLength The length of one side for the new Hexagon
 55 * @example
 56 * var h = new Hexagon(2);
 57 * @example
 58 * if (hasHex) {
 59 *     hex   = new Hexagon(5);
 60 *     color = hex.getColor();
 61 * }
 62 */
 63function Hexagon(sideLength) {
 64}
 65
 66
 67/**
 68 * This is an unattached (static) function that adds two integers together.
 69 * @param {int} One The first number to add 
 70 * @param {int} Two The second number to add 
 71 * @author Gabriel Reid
 72 * @deprecated So you shouldn't use it anymore!
 73 */
 74function Add(One, Two){
 75    return One + Two;
 76}
 77
 78
 79/**
 80 * The color of this shape
 81 * @type Color
 82 */
 83Shape.prototype.color = null;
 84
 85/**
 86 * The border of this shape. 
 87 * @field
 88 * @type int
 89 */
 90Shape.prototype.border = function(){return border;};
 91
 92/*
 93 * These are all the instance method implementations for Shape
 94 */
 95
 96/**
 97 * Get the coordinates of this shape. It is assumed that we're always talking
 98 * about shapes in a 2D location here.
 99 * @requires The {@link Shape} class
100 * @returns A Coordinate object representing the location of this Shape
101 * @type Coordinate[]
102 */
103Shape.prototype.getCoords = function(){
104   return this.coords;
105}
106
107/**
108 * Get the color of this shape.
109 * @see #setColor
110 * @see The <a href="http://example.com">Color</a> library.
111 * @link Shape
112 * @type Color
113 */
114Shape.prototype.getColor = function(){
115   return this.color;
116}
117
118/**
119 * Set the coordinates for this Shape
120 * @param {Coordinate} coordinates The coordinates to set for this Shape
121 */
122Shape.prototype.setCoords = function(coordinates){
123   this.coords = coordinates;
124}
125
126/**
127 * Set the color for this Shape
128 * @param {Color} color The color to set for this Shape
129 * @param other There is no other param, but it can still be documented if
130 *              optional parameters are used
131 * @throws NonExistantColorException (no, not really!)
132 * @see #getColor
133 */
134Shape.prototype.setColor = function(color){
135   this.color = color;
136}
137
138/**
139 * Clone this shape
140 * @returns A copy of this shape
141 * @type Shape
142 * @author Gabriel Reid
143 */
144Shape.prototype.clone = function(){
145   return new Shape();
146}
147
148/**
149 * Create a new Rectangle instance. 
150 * @class A basic rectangle class, inherits from Shape.
151 * This class could be considered a concrete implementation class
152 * @constructor
153 * @param {int} width The optional width for this Rectangle
154 * @param {int} height Thie optional height for this Rectangle
155 * @author Gabriel Reid
156 * @see Shape is the base class for this
157 * @augments Shape
158 * @hilited
159 */
160function Rectangle(width, // This is the width 
161                  height // This is the height
162                  ){
163   if (width){
164      this.width = width;
165      if (height){
166	 this.height = height;
167      }
168   }
169}
170
171
172/* Inherit from Shape */
173Rectangle.prototype = new Shape();
174
175/**
176 * Value to represent the width of the Rectangle.
177 * <br>Text in <b>bold</b> and <i>italic</i> and a 
178 * link to <a href="http://sf.net">SourceForge</a>
179 * @private
180 * @type int
181 */
182Rectangle.prototype.width = 0;
183
184/**
185 * Value to represent the height of the Rectangle
186 * @private
187 * @type int
188 */
189Rectangle.prototype.height = 0;
190
191/**
192 * Get the type of this object. 
193 * @type String
194 */
195Rectangle.prototype.getClassName= function(){
196    return "Rectangle";
197}
198
199/**
200 * Get the value of the width for the Rectangle
201 * @type int
202 * @see Rectangle#setWidth
203 */
204Rectangle.prototype.getWidth = function(){
205   return this.width;
206}
207
208/**
209 * Get the value of the height for the Rectangle.
210 * Another getter is the {@link Shape#getColor} method in the 
211 * {@link Shape} base class.  
212 * @return The height of this Rectangle
213 * @type int
214 * @see Rectangle#setHeight
215 */
216Rectangle.prototype.getHeight = function(){
217    return this.height;
218}
219
220/**
221 * Set the width value for this Rectangle.
222 * @param {int} width The width value to be set
223 * @see #setWidth
224 */
225Rectangle.prototype.setWidth = function(width){
226   this.width = width;
227}
228
229/**
230 * Set the height value for this Rectangle.
231 * @param {int} height The height value to be set
232 * @see #getHeight
233 */
234Rectangle.prototype.setHeight = function(height){
235   this.height = height;
236}
237
238/**
239 * Get the value for the total area of this Rectangle
240 * @return total area of this Rectangle
241 * @type int
242 */
243Rectangle.prototype.getArea = function(){
244   return width * height;
245}
246
247
248/**
249 * Create a new Square instance.
250 * @class A Square is a subclass of {@link Rectangle}
251 * @param {int} width The optional width for this Rectangle
252 * @param {int} height The optional height for this Rectangle
253 * @augments Rectangle
254 */
255function Square(width, height){
256   if (width){
257      this.width = width;
258      if (height){
259	 this.height = height;
260      }
261   } 
262   
263}
264
265/* Square is a subclass of Rectangle */
266Square.prototype = new Rectangle();
267
268/**
269 * Set the width value for this Shape.
270 * @param {int} width The width value to be set
271 * @see #getWidth
272 */
273Square.prototype.setWidth = function(width){
274   this.width = this.height = width;
275}
276
277/**
278 * Set the height value for this Shape 
279 * Sets the {@link Rectangle#height} attribute in the Rectangle.
280 * @param {int} height The height value to be set
281 */
282Square.prototype.setHeight = function(height){
283   this.height = this.width = height;
284}
285
286
287/**
288 * Create a new Circle instance based on a radius.
289 * @class Circle class is another subclass of Shape
290 * @extends Shape
291 * @param {int} radius The optional radius of this {@link Circle }
292 * @mixin Square.prototype.setWidth as this.setDiameter
293 */
294function Circle(radius){
295   if (radius) {
296      /** The radius of the this Circle. */
297      this.radius = radius;
298   }
299}
300
301/* Circle inherits from {@link Shape} */
302Circle.prototype = new Shape();
303
304/** 
305 * The radius value for this Circle 
306 * @private
307 * @type int
308 */
309Circle.prototype.radius = 0;
310
311/** 
312 * A very simple class (static) field that is also a constant
313 * @final
314 * @type float
315 */
316Circle.PI = 3.14;
317
318/**
319 * Get the radius value for this Circle
320 * @type int
321 * @see #setRadius
322 */
323Circle.prototype.getRadius = function(){
324   return this.radius;
325}
326
327/** 
328 * Set the radius value for this Circle
329 * @param {int} radius The {@link Circle#radius} value to set
330 * @see #getRadius
331 */
332Circle.prototype.setRadius = function(radius){
333   this.radius = radius;
334}
335
336/** 
337 * An example of a  class (static) method that acts as a factory for Circle
338 * objects. Given a radius value, this method creates a new Circle.
339 * @param {int} radius The radius value to use for the new Circle.
340 * @type Circle
341 */
342Circle.createCircle = function(radius){
343    return new Circle(radius);
344}
345
346
347/**
348 * Create a new Coordinate instance based on x and y grid data.
349 * @class Coordinate is a class that can encapsulate location information.
350 * @param {int} [x=0] The optional x portion of the Coordinate
351 * @param {int} [y=0] The optinal y portion of the Coordinate
352 */
353function Coordinate(x, y){
354   if (x){
355      this.x = x;
356      if (y){
357	 this.y = y;
358      }
359   }
360}
361
362/** 
363 * The x portion of the Coordinate 
364 * @type int
365 * @see #getX
366 * @see #setX
367 */
368Coordinate.prototype.x = 0;
369
370/** 
371 * The y portion of the Coordinate 
372 * @type int
373 * @see #getY
374 * @see #setY
375 */
376Coordinate.prototype.y = 0;
377
378/**
379 * Gets the x portion of the Coordinate.
380 * @type int
381 * @see #setX
382 */
383Coordinate.prototype.getX = function(){
384   return this.x;
385}
386
387/** 
388 * Get the y portion of the Coordinate.
389 * @type int
390 * @see #setY
391 */
392Coordinate.prototype.getY = function(){
393   return this.y;
394}
395
396/**
397 * Sets the x portion of the Coordinate.
398 * @param {int} x The x value to set
399 * @see #getX
400 */
401Coordinate.prototype.setX = function(x){
402   this.x = x;
403}
404
405/** 
406 * Sets the y portion of the Coordinate.
407 * @param {int} y The y value to set
408 * @see #getY
409 */
410Coordinate.prototype.setY = function(y){
411   this.y = y;
412}
413
414/**
415 * @class This class exists to demonstrate the assignment of a class prototype
416 * as an anonymous block.
417 */
418function ShapeFactory(){
419}
420
421ShapeFactory.prototype = {
422   /** 
423    * Creates a new {@link Shape} instance.
424    * @return A new {@link Shape}
425    * @type Shape
426    */
427   createShape: function(){
428      return new Shape();
429   }
430}
431
432/**
433 * An example of a singleton class
434 * @param ... Arguments represent {@link coordinate}s in the shape.
435 * @constructor
436 */
437MySingletonShapeFactory = function(){
438
439   /**
440    * Get the next {@link Shape}
441    * @type Shape
442    * @return A new {@link Shape}
443    */
444   this.getShape = function(){ 
445      return null; 
446   }
447
448}
449
450
451/** 
452 * Create a new Foo instance.
453 * @class This is the Foo class. It exists to demonstrate 'nested' classes.
454 * @constructor 
455 * @see Foo.Bar
456 */
457function Foo(){}
458
459/** 
460 * Creates a new instance of Bar.
461 * @class This class exists to demonstrate 'nested' classes.
462 * @constructor 
463 * @see Foo.Bar
464 */
465function Bar(){}
466
467/** 
468 * Nested class
469 * @constructor 
470 */
471Foo.Bar = function(){
472	/** The x. */ this.x = 2;
473}
474
475Foo.Bar.prototype = new Bar();
476/** The y. */ 
477Foo.Bar.prototype.y = '3';