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