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  */
  23 function 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  */
  63 function 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! Use {@link Shape#getClassName} instead.
  73  */
  74 function Add(One, Two){
  75     return One + Two;
  76 }
  77
  78
  79 /**
  80  * The color of this shape
  81  * @type Color
  82  */
  83 Shape.prototype.color = null;
  84
  85 /**
  86  * The border of this shape.
  87  * @field
  88  * @type int
  89  */
  90 Shape.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  */
 103 Shape.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  */
 114 Shape.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  */
 122 Shape.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  */
 134 Shape.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  */
 144 Shape.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  */
 160 function 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 */
 173 Rectangle.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  */
 182 Rectangle.prototype.width = 0;
 183
 184 /**
 185  * Value to represent the height of the Rectangle
 186  * @private
 187  * @type int
 188  */
 189 Rectangle.prototype.height = 0;
 190
 191 /**
 192  * Get the type of this object.
 193  * @type String
 194  */
 195 Rectangle.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  */
 204 Rectangle.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  */
 216 Rectangle.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  */
 225 Rectangle.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  */
 234 Rectangle.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  */
 243 Rectangle.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  */
 255 function 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 */
 266 Square.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  */
 273 Square.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  */
 282 Square.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  */
 294 function 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} */
 302 Circle.prototype = new Shape();
 303
 304 /**
 305  * The radius value for this Circle
 306  * @private
 307  * @type int
 308  */
 309 Circle.prototype.radius = 0;
 310
 311 /**
 312  * A very simple class (static) field that is also a constant
 313  * @final
 314  * @type float
 315  */
 316 Circle.PI = 3.14;
 317
 318 /**
 319  * Get the radius value for this Circle
 320  * @type int
 321  * @see #setRadius
 322  */
 323 Circle.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  */
 332 Circle.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  */
 342 Circle.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  */
 353 function 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  */
 368 Coordinate.prototype.x = 0;
 369
 370 /**
 371  * The y portion of the Coordinate
 372  * @type int
 373  * @see #getY
 374  * @see #setY
 375  */
 376 Coordinate.prototype.y = 0;
 377
 378 /**
 379  * Gets the x portion of the Coordinate.
 380  * @type int
 381  * @see #setX
 382  */
 383 Coordinate.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  */
 392 Coordinate.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  */
 401 Coordinate.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  */
 410 Coordinate.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  */
 418 function ShapeFactory(){
 419 }
 420
 421 ShapeFactory.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  */
 437 MySingletonShapeFactory = 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  */
 457 function 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  */
 465 function Bar(){}
 466
 467 /**
 468  * Nested class
 469  * @constructor
 470  */
 471 Foo.Bar = function(){
 472         /** The x. */ this.x = 2;
 473 }
 474
 475 Foo.Bar.prototype = new Bar();
 476 /** The y. */
 477 Foo.Bar.prototype.y = '3';