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';