📝 Add documentation to several pandora files (14/30)

- Update documentation on GameHandler and AssetHandler Handlers,
- Update documentation on GameObject.
- Add documentation to Object2D, Shape2D, Sprite2D and AnimatedSprte2D GameObjects,
- Add documentation to Timer and AudioPlayer GameObjects,
- Add documentation to UIObject, Button, CheckBox and ColorPicker GameObjects.

pandora/game_objects/2d_objects/AnimatedSprite2D.js

@@ -19,8 +19,27 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code AnimatedSprite2D} class represents a GameObject that inherits from
+ * Sprite2D and extends its functionality to automatically draw a series of sprites
+ * to the screen forming an animation.
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class AnimatedSprite2D extends Sprite2D
 {
+    /**
+     * @constructor
+     * Initializes as AnimatedSprite2D GameObject with the specified parameters.
+     * 
+     * @param {String} name                 name for this AnimatedSprite2D GameObject. 
+     * @param {p5.Image} p5Image            this AnimatedSprite2D's p5.Image to be drawn
+     *                                      to the buffer.
+     * @param {SpriteFrames} spriteFrames   data holding the animation in frames to be
+     *                                      played by this GameObject.
+     */
     constructor(name, p5Image, spriteFrames)
     {
         super(name, p5Image);
@@ -32,7 +51,15 @@ class AnimatedSprite2D extends Sprite2D
         this.timeSinceLastFrame = 0;
     }
 
-    // Setters
+    /**
+     * Sets the current SpriteAnimation to be played based on its index on the list of
+     * animations on SpriteFrames. Does nothing if the index is invalid.
+     * 
+     * ! The index refers to the order you added the animations to this AnimatedSprite2D's
+     * ! SpriteFrames, starting at 0.
+     * 
+     * @param {number} idx  index of the SpriteAnimation on SpriteFrames.
+     */
     setCurrentAnimationByIndex(idx)
     {
         if (idx < this.spriteFrames.numAnimations)
@@ -42,6 +69,12 @@ class AnimatedSprite2D extends Sprite2D
         this.timeSinceLastFrame = 0;
     }
 
+    /**
+     * Sets the current SpriteAnimation to be played based on its name on the list of
+     * animations on SpriteFrames. Does nothing if the name is invalid.
+     * 
+     * @param {String} name name of the SpriteAnimation on SpriteFrames.
+     */
     setCurrentAnimationByName(name)
     {
         this.currentAnimation = this.spriteFrames.getAnimationIndexByName(name);
@@ -49,58 +82,118 @@ class AnimatedSprite2D extends Sprite2D
         this.timeSinceLastFrame = 0;
     }
 
+    /**
+     * Sets the current SpriteAnimation's time between frames.
+     * 
+     * @param {number} time new time in seconds between frames for the
+     *                      current SpriteAnimation.
+     */
     setCurrentFrameTime(time)
     {
         this.getCurrentAnimation().setFrameTime(time);
     }
 
+    /**
+     * Sets the current SpriteAnimation's frames per second.
+     * 
+     * @param {number} fps  new frames per second for the current SpriteAnimation.
+     */
     setCurrentFPS(fps)
     {
         this.getCurrentAnimation().setFPS(fps);
     }
 
-    // Getters
+    /**
+     * Returns the SpriteAnimation with the given index on the list os SpriteAnimations on
+     * this AnimatedSprite2D's SpriteFrames.
+     * 
+     * ! The index refers to the order you added the animations to this AnimatedSprite2D's
+     * ! SpriteFrames, starting at 0.
+     * 
+     * @param {number} idx  index of the desired SpriteAnimation on SpriteFrames' list.
+     * 
+     * @returns {SpriteAnimation}   the desired SpriteAnimation based on the given index,
+     *                              or null if the index is invalid.
+     */
     getAnimationByIndex(idx)
     {
         return this.spriteFrames.getAnimationByIndex(idx);
     }
 
+    /**
+     * Returns the current SpriteAnimation on this AnimatedSprite2D's Sprite Frames.
+     * 
+     * @returns {SpriteAnimation}   the current SpriteAnimation on the SprteFrames.
+     */
     getCurrentAnimation()
     {
         return this.spriteFrames.getAnimationByIndex(this.currentAnimation);
     }
 
+    /**
+     * Rerturns the p5.Image of the current frame on the current SpriteAnimation.
+     * 
+     * @returns {p5.Image}  image of the current frame. 
+     */
     getCurrentFrame()
     {
         return this.getCurrentAnimation().getFrame(this.frame);
     }
 
+    /**
+     * Returns the time in seconds between frames of the current SpriteAnimation.
+     * 
+     * @returns {number}    time in seconds between frames of the current SpriteAnimation.
+     */
     getCurrentFrameTime()
     {
         return this.getCurrentAnimation().getFrameTime();
     }
 
+    /**
+     * Returns the number of frames of the current SpriteAnimation.
+     * 
+     * @returns {number}    number of frames of the current SpriteAnimation.
+     */
     getCurrentNumFrames()
     {
         return this.getCurrentAnimation().getNumFrames();
     }
 
-    // Methods
+    /**
+     * Starts playing the current SpriteAnimation.
+     */
     play()
     {
         this.playing = true;
     }
 
+    /**
+     * Stops playing the current SpriteAnimation.
+     */
     stop()
     {
         this.playing = false;
     }
 
+    /**
+     * Rerturns the playing state of the current SpriteAnimation.
+     * 
+     * @returns {boolean}   true if the animation is playing, false if not. 
+     */
     isPlaying()
     {
         return this.playing;
     }
 
+    /**
+     * @override
+     * Updates the current SpriteAnimation if its playing, and updates this
+     * AnimatedSprite2D's P5Image to the current frame based on the current
+     * SpriteAnimation.
+     * 
+     * @param {number} delta    number of seconds ellapsed since the last frame. 
+     */
     update(delta)
     {
         if (this.playing)
@@ -112,6 +205,7 @@ class AnimatedSprite2D extends Sprite2D
                 this.timeSinceLastFrame = 0;
             }
         }
+        
         this.P5Image = this.getCurrentFrame();
         this._update(delta);
         for (let i = 0; i < this.children.length; i++)

pandora/game_objects/2d_objects/Object2D.js

@@ -19,56 +19,99 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Object2D} class represents a GameObject that has a transform,
+ * comprised of a position, a rotation in degrees and a scale. All parameters
+ * of this transform are relative to the parent of this GameObject, if it has one.
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Object2D extends GameObject
 {
+    /**
+     * @constructor
+     * Initializes an empty Object2D GameObject.
+     * 
+     * @param {String} name name of the Object2D GameObject. 
+     */
     constructor(name)
     {
         super(name);
 
-        this.position = Vector2.ZERO();
-        this.rotationDegrees = 0;
-        this.scale = Vector2.ONE();
-        this.visible = true;
+        this.position = Vector2.ZERO(); // This Object2D's position on the secondary buffer.
+        this.rotationDegrees = 0; // This Object2D's rotation degrees on the secondary buffer.
+        this.scale = Vector2.ONE(); // This Object2D's scale on the secondary buffer.
+        this.visible = true; // Is this Object2D visible at the moment?
     }
 
+    /**
+     * Sets the visibility flag of this Object2D and all of its children
+     * that have a visibility flag to true.
+     */
     show()
     {
         this.visible = true;
 
         for (let i = 0; i < this.children.length; i++)
         {
-            if(!this.children[i].show) continue;
+            if (!this.children[i].show) continue;
             this.children[i].show();
         }
     }
 
+    /**
+     * Sets the visibility flag of this Object2D and all of its children
+     * that have a visibility flag to false.
+     */
     hide()
     {
         this.visible = false;
 
         for (let i = 0; i < this.children.length; i++)
         {
-            if(!this.children[i].hide) continue;
+            if (!this.children[i].hide) continue;
             this.children[i].hide();
         }
     }
 
+    /**
+     * Sets the visibility flag of this Object2D and all of its children that have a visibility
+     * flag to the provided value.
+     * 
+     * @param {boolean} val value to set the flag to.
+     */
     setVisibility(val)
     {
         this.visible = val;
 
         for (let i = 0; i < this.children.length; i++)
         {
-            if(!this.children[i].setVisibility) continue;
+            if (!this.children[i].setVisibility) continue;
             this.children[i].setVisibility(val);
         }
     }
 
+    /**
+     * Returns this Object2D's visibility flag.
+     * 
+     * @returns {boolean} true if this Object2D is visible, false if not.
+     */
     getVisibility()
     {
         return this.visible;
     }
 
+    /**
+     * @override
+     * Applies this Object2D's transform before calling this GameObject's _draw() callback
+     * and recursively calls the same callback on all of it's children. This results in the
+     * appearence of relative position.
+     * 
+     * @param {number} delta    number of seconds ellapsed since the last frame.
+     * @param {p5.Graphics} db  secondary buffer to draw to.
+     */
     draw(delta, db)
     {
         if (!this.visible) return;
@@ -77,6 +120,7 @@ class Object2D extends GameObject
         db.translate(this.position.x, this.position.y);
         db.rotate(this.rotationDegrees);
         db.scale(this.scale.x, this.scale.y);
+
         this._draw(delta, db);
 
         for (let i = 0; i < this.children.length; i++)

pandora/game_objects/2d_objects/Shape2D.js

@@ -19,23 +19,49 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Shape2D} class represents a GameObject that inherits from
+ * Object2D and extends its functionality to automatically draw a Shape on the
+ * buffer, according to the data passed by a Shape component.
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Shape2D extends Object2D
 {
+    /**
+     * @constructor
+     * Initializes a Shape2D GameObject with the specified parameters.
+     * 
+     * @param {String} name         name for this Shape2D;
+     * @param {SHAPES} shapeType    type of the shape for this Shape2D. 
+     * @param {Shape} shape         dta for the shape of this Shape2D.
+     */
     constructor(name, shapeType = null, shape = null)
     {
         super(name);
 
-        this.shapeType = shapeType;
-        this.shape = shape;
+        this.shapeType = shapeType; // This Shape2D's shape type.
+        this.shape = shape; // This Shape2D's shape data.
 
-        this.shapeMode = CORNER;
-        this.fillColor = color(255);
-        this.noFill = false;
-        this.strokeWeight = 1;
-        this.strokeColor = color(0);
-        this.noStroke = false;
+        this.shapeMode = CORNER; // This Shape2D's shape mode.
+        this.fillColor = color(255); // This Shape2D's fill color.
+        this.noFill = false; // Should this Shape2D be filled with a color?
+        this.strokeWeight = 1; // This Shape2D's stroke weight.
+        this.strokeColor = color(0); // This Shape2D's stroke color.
+        this.noStroke = false; // Should this Shape2D have an outline?
     }
 
+    /**
+     * @override
+     * Applies this Object2D's transform before calling this GameObject's _draw() callback
+     * and recursively calls the same callback on all of it's children. Also draws a shape
+     * on the buffer based on the data passed to this GameObject.
+     * 
+     * @param {number} delta    number in seconds ellapsed since the last frame.
+     * @param {p5.Graphics} db  secondary buffer to draw to.
+     */
     draw(delta, db)
     {
         db.push();

pandora/game_objects/2d_objects/Sprite2D.js

@@ -19,15 +19,40 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Sprite2D} class represents a GameObject that inherits from
+ * Object2D and extends its functionality to automatically draw a Sprite on the
+ * buffer.
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Sprite2D extends Object2D
 {
+    /**
+     * @constructor
+     * Initializes a Sprite2D GameObject with the specified parameters.
+     * 
+     * @param {String} name         name for this Sprite2D. 
+     * @param {p5.Image} p5Image    p5.Image to be drawn on the buffer.
+     */
     constructor(name, p5Image)
     {
         super(name);
 
-        this.P5Image = p5Image;
+        this.P5Image = p5Image; // This Sprite2D p5.Image.
     }
 
+    /**
+     * @override
+     * Applies this Object2D's transform before calling this GameObject's _draw() callback
+     * and recursively calls the same callback on all of it's children. Also draws an image
+     * on the buffer based on the data passed to this GameObject.
+     * 
+     * @param {number} delta    number in seconds ellapsed since the last frame.
+     * @param {p5.Graphics} db  secondary buffer to draw to.
+     */
     draw(delta, db)
     {
         db.push();

pandora/game_objects/AudioPlayer.js

@@ -19,8 +19,23 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code AudioPlayer} class represents a GameObject that can playa p5.Audio
+ * loaded from the AssetHandler.
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class AudioPlayer extends GameObject
 {
+    /**
+     * @constructor
+     * Initializes an AudioPlayer GameObject with the given parameters.
+     * 
+     * @param {String} name         name for the AudioPlayer GameObject.
+     * @param {p5.Audio} p5Audio    p5.Audio this AudioPlayer will play from.
+     */
     constructor(name, p5Audio = null)
     {
         super(name);
@@ -28,29 +43,49 @@ class AudioPlayer extends GameObject
         this.p5Audio = p5Audio;
     }
 
+    /**
+     * Overrides AudioPlayer's p5Audio.
+     * 
+     * @param {p5.Audio} p5Audio    new p5.Audio for this AudioPlayer to play from.
+     */
     setP5Audio(p5Audio)
     {
         if (this.p5Audio) this.p5Audio.stop();
         this.p5Audio = p5Audio;
     }
 
+    /**
+     * Returns this AudioPlayer's p5Audio.
+     * 
+     * @returns {p5.Audio}  this AudioPlayer's p5Audio.
+     */
     getP5Audio()
     {
         return this.p5Audio;
     }
 
+    /**
+     * Starts playing this AudioPlayer's p5Audio.
+     */
     play()
     {
         if (this.p5Audio) this.p5Audio.play();
     }
 
+    /**
+     * Stops playing this AudioPlayer's p5Audio.
+     */
     stop()
     {
         if (this.p5Audio) this.p5Audio.stop();
     }
 
-    // TODO: This don't worky, make it worky
-    // Something to do with new browser audio policy
+    // TODO: This don't worky, make it worky.
+    // Something to do with new browser audio policy.
+    /**
+     * Sets this AudioPlayer's autoplay falg to true, so it starts whenever
+     * it is ready.
+     */
     autoplay()
     {
         if (this.p5Audio) this.p5Audio.autoplay(true);

pandora/game_objects/GameObject.js

@@ -59,8 +59,8 @@ class GameObject
 
     /**
      * Returns the list of children of this GameObject.
-     * @returns Array containing a reference to all of this GameObject's
-     *          children.
+     * @returns {Array} array containing a reference to all of this GameObject's
+     *                  children.
      */
     getChildren()
     {
@@ -76,8 +76,8 @@ class GameObject
      * @param {String} idx  index of the desired child on the GameObject's
      *                      children list.
      * 
-     * @returns a reference to the child with the given index, or null if
-     *          no child has that index. 
+     * @returns {GameObject}    a reference to the child with the given index, or null if
+     *                          no child has that index. 
      */
     getChildByIndex(idx)
     {
@@ -92,8 +92,8 @@ class GameObject
      * @param {String} id  id of the desired child on the GameObject's
      *                      children list.
      * 
-     * @returns a reference to the child with the given id, or null if
-     *          no child has that id. 
+     * @returns {GameObject}    a reference to the child with the given id, or null if
+     *                          no child has that id. 
      */
     getChildById(id)
     {
@@ -110,8 +110,8 @@ class GameObject
      * 
      * @param {String} name name of the desired child.
      *  
-     * @returns a reference to the child with the given name, or null
-     *          if no child has that name. 
+     * @returns {GameObject}    a reference to the child with the given name, or null
+     *                          if no child has that name. 
      */
     getChildByName(name)
     {
@@ -123,8 +123,8 @@ class GameObject
     /**
      * Get a reference to this GameObject's parent.
      * 
-     * @returns a reference to this GameObject's parent if it exists, null
-     *          if it doesn't.
+     * @returns {GameObject}    a reference to this GameObject's parent if it
+     *                          exists, null if it doesn't.
      */
     getParent()
     {

pandora/game_objects/Timer.js

@@ -19,8 +19,28 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Timer} class represents a Timer GameObject with the functionality
+ * of emiting a signal after some amount of time passed.
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Timer extends GameObject
 {
+    /**
+     * @constructor
+     * Initializes a Timer GameObject with the given parameters.
+     * 
+     * @param {String} name         name for this Timer GameObject.
+     * @param {number} duration     duration in seconds of the timer.
+     *                              Default is 1 second.
+     * @param {boolean} autostart   shuold the timer start automaticaly
+     *                              when it enters the tree? Default is false.
+     * @param {boolean} oneShot     should the timer run only once?
+     *                              Default is false.
+     */
     constructor(name, duration = 1, autostart = false, oneShot = false)
     {
         super(name);
@@ -32,6 +52,13 @@ class Timer extends GameObject
         this.oneShot = oneShot;
     }
 
+    /**
+     * Starts counting the Timer if it is paused, and does nothing if
+     * the Timer is already running.
+     * 
+     * @param {number} timeSec  duration in seconds to override Timer's duration.
+     *                          Defaults to current Timer's duration.
+     */
     start(timeSec = this.duration)
     {
         if (!this.paused) return;
@@ -40,21 +67,53 @@ class Timer extends GameObject
         this.timeLeft = this.duration;
     }
 
+    /**
+     * Pauses the Timer. Does nothing if already paused.
+     */
     stop()
     {
         this.paused = true;
     }
 
+    /**
+     * Resumes the Timer. Does nothing if already running.
+     */
     resume()
     {
         this.paused = false;
     }
 
+    /**
+     * Returns the paused state of the Timer.
+     * 
+     * @returns {boolean} true if the timer is paused, false if not.
+     */
     isStopped()
     {
         return this.paused;
     }
 
+    /**
+     * This function is called when the timer is done and serves
+     * to change the data of the timer accordingly and emit the
+     * timeout signal.
+     */
+    onFinish()
+    {
+        if (this.oneShot) this.paused = true
+        this.timeLeft = this.duration;
+        this._onFinish();
+        this.emitSignal("timeout");
+    }
+
+    /**
+     * @override
+     * Updates the Timer and calls the onFinish() function if the timer ended.
+     * Also recursively calls the update() function for all of this GameObject's
+     * children.
+     * 
+     * @param {number} delta    time in seconds ellapsed since the last frame. 
+     */
     update(delta)
     {
         if (!this.paused)
@@ -68,22 +127,27 @@ class Timer extends GameObject
             this.children[i].update(delta);
     }
 
+    /**
+     * @override
+     * Adds default signals for the Timer GameObject and serves as a caller
+     * to the _initSignals() callback.
+     * 
+     * @signal timeout  emited once every time this timer is done.
+     */
     initSignals()
     {
         this.addSignal("timeout");
         this._initSignals();
     }
 
-    onFinish()
-    {
-        if (this.oneShot) this.paused = true
-        this.timeLeft = this.duration;
-        this._onFinish();
-        this.emitSignal("timeout");
-    }
-
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time the Timer is done and can be used in
+     * objects that inherit from Timer to add functinoality this event.
+     */
     _onFinish()
     {
-        console.log("doneskis");
+
     }
 }

pandora/game_objects/Tween.js

@@ -19,7 +19,7 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
-/**'
+/**
  * The {@code TweenData} class represents the data that a Tween GameObject needs to
  * interpolate a given property.
  * 

pandora/game_objects/ui_objects/Button.js

@@ -19,22 +19,44 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Button} class represents an UIObject that holds and HTML button.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Button extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes an empty Button GameObject.
+     * 
+     * @param {String} name 
+     * @param {String} label 
+     */
     constructor(name, label = "Button")
     {
         super(name);
 
-        this.P5Element = createButton();
-        this.label = label;
-        this.P5Element.html(label);
-        this.P5Element.position(0, 0);
+        this.P5Element = createButton(); // This Button's HTML button.
+        this.label = label; // This Button's label
+        this.P5Element.html(label); // Set the label to the inner HTML of the button.
+        this.setPosition(0, 0); // Set the position of the Button on the secondary buffer.
 
-        this.setStyle(STYLE.DEFAULT_STYLE);
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set the default style of the UIObject.
 
-        this.connectCallbacks();
+        this.connectCallbacks(); // Connect the events of the p5.Element.
     }
 
+    /**
+     * Sets the label on this UIObject's button.
+     * 
+     * @param {String} label    new label for the button.
+     */
     setLabel(label)
     {
         this.label = label;

pandora/game_objects/ui_objects/CheckBox.js

@@ -19,33 +19,82 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code CheckBox} class represents an UIObject that holds and HTML checkbox.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class CheckBox extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes an empty CheckBox GameObject.
+     * 
+     * @param {String} name     name for the CheckBox GameObject. 
+     * @param {String} label    label for the CheckBox GameObject.
+     * @param {boolean} val     initial value for the CheckBox. True
+     *                          for checked, false for unchecked.
+     */
     constructor(name, label = "checkbox", val = false)
     {
         super(name);
 
-        this.label = label;
-        this.P5Element = createCheckbox(label, val);
-        this.P5Element.position(0, 0);
+        this.label = label; // This Button's HTML checkbox
+        this.P5Element = createCheckbox(label, val); // This Button's label
+        this.setPosition(0, 0); // Set the position of the Button on the secondary buffer.
 
-        this.setStyle(STYLE.DEFAULT_STYLE);
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set the default style of the UIObject.
 
-        this.connectCallbacks();
-        this.P5Element.changed(this.onChanged);
+        this.connectCallbacks(); // Connect the events of the p5.Element.
+        this.P5Element.changed(this.onChanged); // Connect the extra event checkboxes have
     }
 
+    /**
+     * Sets the label on this UIObject's checkbox.
+     * 
+     * @param {String} label    new label for the checkbox.
+     */
     setLabel(label)
     {
         this.label = label;
         this.P5Element.html(label);
     }
 
-    _onChanged()
-    {
-        console.log(this.P5Element.checked());
-    }
-
+    /**
+     * @override
+     * Defines default signals for UIObjects and serves as the caller to this UIObject's
+     * _initSignals() callbacks. Also adds the extra onChaged signal for CheckBoxes.
+     * 
+     * @signal mousePressed     emited once every time a mouse button is pressed over this
+     *                          UIObject.
+     * @signal doubleClicked    emited once every time a mouse button is pressed twice over
+     *                          this UIObject.
+     * @signal mouseWheel       emited once everty time a mouse wheel is scrolled over this
+     *                          UIObject. Passes one argument {event} that holds the deltaY
+     *                          property, that holds a number based on how much was vertically
+     *                          scrolled (up is positive) and the deltaX property, that holds a
+     *                          number based on how much was horizontaly scrolled (right is positive).
+     * @signal mouseReleased    emited once every time a mouse button is released over this
+     *                          UIObject.
+     * @signal mouseClicked     emited once every time a mouse button is pressed and released
+     *                          over this UIObject.
+     * @signal mouseMoved       emited once every time a mouse moves over this UIObject.
+     * @signal mouseOver        emited once every time a mouse moves onto this UIObject.
+     * @signal mouseOut         emited once every time a mouse moves out of this UIObject.
+     * @signal touchStarted     emited once every time a touch is regiestered over this UIObject.
+     * @signal touchMoved       emited once every time a touch move is regiestered over this
+     *                          UIObject.
+     * @signal touchEnded       emited once every time a touch is regiestered over this UIObject.
+     * @signal dragOver         emited once every time a file is dragged over this UIObject.
+     * @signal dragLeave        emited once every time a dragged file leaves this UIObject's area.
+     * 
+     * @signal changed          emited once every time this UIObject's checkbox's value is changed.
+     */
     initSignals()
     {
         this.addSignal("mousePressed");
@@ -62,13 +111,29 @@ class CheckBox extends UIObject
         this.addSignal("dragOver");
         this.addSignal("dragLeave");
 
-        this.addSignal("changed")
+        this.addSignal("changed");
         this._initSignals();
     }
 
+    /**
+     * Called once every time this UIObject's checkbox's value is changed.
+     * Connected to the changed event from this UIObject's p5.Element.
+     * Serves as an emiter to the changed signal and calls the _onChanged()
+     * callback.
+     */
     onChanged()
     {
         this.pandoraObject.emitSignal("changed");
         this.pandoraObject._onChanged();
     }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time this UIObject's checkbox's value is changed.
+     */
+    _onChanged()
+    {
+        console.log(this.P5Element.checked());
+    }
 }

pandora/game_objects/ui_objects/ColorPicker.js

@@ -19,19 +19,52 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code ColorPicker} class represents an UIObject that holds and HTML color picker.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class ColorPicker extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes an empty ColorPicker with the specified parameters.
+     * 
+     * @param {String} name             name for the ColorPicker GameObject.
+     * @param {p5.Color, String} color  default color for the ColorPicker
+     */
     constructor(name, color = "#FFFFFF")
     {
         super(name);
 
-        this.P5Element = createColorPicker(color);
-        this.setPosition(0, 0);
-        this.setStyle(STYLE.DEFAULT_STYLE);
+        this.P5Element = createColorPicker(color); // This Button's HTML color picker.
+        this.setPosition(0, 0); // Set the position of the ColorPicker on the secondary buffer.
 
-        this.connectCallbacks();
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set the default style of the UIObject.
+
+        this.connectCallbacks(); // Connect the events of the p5.Element.
+    }
+
+    /**
+     * Sets the color of this ColorPicker UIObject.
+     * 
+     * @param {p5.Color, String} col    new color for this ColorPicker.
+     */
+    setColor(col)
+    {
+        this.P5Element.color(col);
     }
 
+    /**
+     * Returns this ColorPicker's color.
+     * 
+     * @returns {p5.Color}  this ColorPicker's color.
+     */
     getColor()
     {
         return this.P5Element.color();

pandora/game_objects/ui_objects/UIObject.js

@@ -19,19 +19,40 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code UIObject} class represents a minimal structure for any GameObject that
+ * hold an HTML interface element.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class UIObject extends GameObject
 {
+    /**
+     * @constructor
+     * Initializes an empty UIObject.
+     * 
+     * @param {String} name name for this UIObject. 
+     */
     constructor(name)
     {
         super(name);
 
-        this.P5Element = null;
-        this.visible = true;
-        this.position = new Vector2(0, 0);
-        this.size = new Vector2(300, 100);
-        this.fontSize = STYLE.DEFAULT_FONT_SIZE;
+        this.P5Element = null; // This UIOBject's p5.Element (that holds an HTML element).
+        this.visible = true; // Is this UIObject visible at the moment?
+        this.position = new Vector2(0, 0); // This UIObject's position on the secondary buffer.
+        this.size = new Vector2(300, 100); // The UIObject's size on the secondary buffer.
+        this.fontSize = STYLE.DEFAULT_FONT_SIZE; // This UIObject's font style.
     }
 
+    /**
+     * Connects this UIObject's p5.Element's events to this GameObject's appropriate
+     * methods.
+     */
     connectCallbacks()
     {
         this.P5Element.mousePressed(this.onMousePressed);
@@ -51,24 +72,45 @@ class UIObject extends GameObject
         this.P5Element.pandoraObject = this;
     }
 
-    // Setters
+    /**
+     * Sets the position of this UIObject on the secondary buffer.
+     * 
+     * @param {number} x    pixel position on the X axis.
+     * @param {number} y    pixel position on the Y axis.
+     */
     setPosition(x, y)
     {
         this.position.x = x;
         this.position.y = y;
     }
 
+    /**
+     * Sets the size of this UIObject on the secondary buffer.
+     * 
+     * @param {number} w    pixel width of this UIObject. 
+     * @param {number} h    pixel height of this UIObject.
+     */
     setSize(w, h)
     {
         this.size.x = w;
         this.size.y = h;
     }
 
+    /**
+     * Sets this UIObject's font size.
+     * 
+     * @param {number} fs   new font size.
+     */
     setFontSize(fs)
     {
         this.fontSize = fs;
     }
 
+    /**
+     * Sets the visibility of this UIObject's p5.Element's visibility.
+     * 
+     * @param {boolean} vis new value for the visibility of the UIObject.
+     */
     setVisibility(vis)
     {
         if (vis) this.P5Element.show();
@@ -76,11 +118,22 @@ class UIObject extends GameObject
         this.visible = !this.visible;
     }
 
+    /**
+     * Sets the inner html value of this UIObject's p5.Element.
+     * 
+     * @param {*} val   new inner HTML value for this UIObject.
+     */
     setValue(val)
     {
         this.P5Element.value(val)
     }
 
+    /**
+     * Sets the CSS style of this UIObject's p5.Element.
+     * 
+     * @param {Object} style    object containing the CSS style for this
+     *                          UIObject. 
+     */
     setStyle(style)
     {
         for (const [key, value] of Object.entries(style))
@@ -89,33 +142,61 @@ class UIObject extends GameObject
         }
     }
 
-    // Getters
+    /**
+     * Returns this UIOBject's position on the secondary buffer.
+     * 
+     * @returns {Vector2} this UIObject's position on the secondary buffer.
+     */
     getPosition()
     {
         return this.position;
     }
 
+    /**
+     * Returns this Object's position on the secondary buffer.
+     * 
+     * @returns {Vector2}   this UIObject's size on the secondary buffer.
+     */
     getSize()
     {
         return this.size;
     }
 
+    /**
+     * Returns this UIObject's font size.
+     * 
+     * @returns {number}    this UIObject's font size.
+     */
     getFontSize()
     {
         return this.fontSize;
     }
 
+    /**
+     * Returns this UIObject's visibility flag.
+     * 
+     * @returns {boolean}   true if this UIObject is visible, false if not.
+     */
     getVisibility()
     {
         return this.visible;
     }
 
+    /**
+     * Return the inner HTML value of this UIObject's p5.Element.
+     * 
+     * @returns {String}    inner HTML value of this UIObject's p5.Element. 
+     */
     getValue()
     {
         return this.P5Element.value();
     }
 
-    // Methods
+    /**
+     * Sets this UIObject's visibility flag to true, shows the p5.Element, and
+     * recursively calls the show() method on all of this GameObject's children 
+     * if they have it.
+     */
     show()
     {
         this.visible = true;
@@ -128,6 +209,11 @@ class UIObject extends GameObject
         }
     }
 
+    /**
+     * Sets this UIObject's visibility flag to false, hides the p5.Element, and
+     * recursively calls the hide() method on all of this GameObject's children 
+     * if they have it.
+     */
     hide()
     {
         this.visible = false;
@@ -140,15 +226,28 @@ class UIObject extends GameObject
         }
     }
 
+    /**
+     * @override
+     * Adds a GameObject as a child of this UIObject, and parents the child's p5.Element
+     * if they are a UIObject.
+     * 
+     * @param {GameObject} child 
+     */
     addChild(child)
     {
         child.parent = this;
         child.parented = true;
         this.children.push(child);
 
-        child.P5Element.parent(this.P5Element);
+        if (child.P5Element)
+            child.P5Element.parent(this.P5Element);
     }
 
+    /**
+     * @override
+     * Recursively marks this GameObject's and all of its children's
+     * memory for garbage collection. Also removes this UIObject's p5.Element.
+     */
     destroy()
     {
         for (let i = 0; i < this.children.length; i++)
@@ -161,76 +260,34 @@ class UIObject extends GameObject
             this[prop] = null;
     }
 
-    // Callbacks
-
-
-    _onMousePressed()
-    {
-
-    }
-
-    _onDoubleClicked()
-    {
-
-    }
-
-    _onMouseWheel()
-    {
-
-    }
-
-    _onMouseReleased()
-    {
-
-    }
-
-    _onMouseClicked()
-    {
-
-    }
-
-    _onMouseMoved()
-    {
-
-    }
-
-    _onMouseOver()
-    {
-
-    }
-
-    _onMouseOut()
-    {
-
-    }
-
-    _onTouchStarted()
-    {
-
-    }
-
-    _onTouchMoved()
-    {
-
-    }
-
-    _onTouchEnded()
-    {
-
-    }
-
-    _onDragOver()
-    {
-
-    }
-
-    _onDragLeave()
-    {
-
-    }
-
-    // -----------------------------------------------
-
+    /**
+     * @override
+     * Defines default signals for UIObjects and serves as the caller to this UIObject's
+     * _initSignals() callbacks.
+     * 
+     * @signal mousePressed     emited once every time a mouse button is pressed over this
+     *                          UIObject.
+     * @signal doubleClicked    emited once every time a mouse button is pressed twice over
+     *                          this UIObject.
+     * @signal mouseWheel       emited once everty time a mouse wheel is scrolled over this
+     *                          UIObject. Passes one argument {event} that holds the deltaY
+     *                          property, that holds a number based on how much was vertically
+     *                          scrolled (up is positive) and the deltaX property, that holds a
+     *                          number based on how much was horizontaly scrolled (right is positive).
+     * @signal mouseReleased    emited once every time a mouse button is released over this
+     *                          UIObject.
+     * @signal mouseClicked     emited once every time a mouse button is pressed and released
+     *                          over this UIObject.
+     * @signal mouseMoved       emited once every time a mouse moves over this UIObject.
+     * @signal mouseOver        emited once every time a mouse moves onto this UIObject.
+     * @signal mouseOut         emited once every time a mouse moves out of this UIObject.
+     * @signal touchStarted     emited once every time a touch is regiestered over this UIObject.
+     * @signal touchMoved       emited once every time a touch move is regiestered over this
+     *                          UIObject.
+     * @signal touchEnded       emited once every time a touch is regiestered over this UIObject.
+     * @signal dragOver         emited once every time a file is dragged over this UIObject.
+     * @signal dragLeave        emited once every time a dragged file leaves this UIObject's area.
+     */
     initSignals()
     {
         this.addSignal("mousePressed");
@@ -246,9 +303,21 @@ class UIObject extends GameObject
         this.addSignal("touchEnded");
         this.addSignal("dragOver");
         this.addSignal("dragLeave");
+
         this._initSignals();
     }
 
+    /**
+     * @override
+     * Updates this UIObject's p5.Element size, position and font size based
+     * on the secondary buffer's size on the actual window. This gives the
+     * impression that the HTML element is actually beeing drawn to the secondary
+     * buffer instead of the main one.
+     * ? is it possible to draw them directly to the secondary buffer?
+     * 
+     * @param {number} delta 
+     * @param {p5.Graphics} db 
+     */
     draw(delta, db)
     {
         let ar = db.screenWidth / db.width;
@@ -267,81 +336,297 @@ class UIObject extends GameObject
             this.children[i].draw(delta, db);
     }
 
+    /**
+     * Called once every time a mouse button is pressed over this UIObject.
+     * Connected to the mousePressed event from this UIObject's p5.Element.
+     * Serves as an emiter to the mousePressed signal and calls the _onMousePressed()
+     * callback.
+     */
     onMousePressed()
     {
         this.pandoraObject.emitSignal("mousePressed");
         this.pandoraObject._onMousePressed();
     }
 
+    /**
+     * Called once every time a mouse button in pressed twice over this UIObject.
+     * Connected to the doubleClicked event from this UIObject's p5.Element.
+     * Serves as an emiter to the doubleClicked signal and calls the _onDoubleClicked()
+     * callback.
+     */
     onDoubleClicked()
     {
         this.pandoraObject.emitSignal("doubleClicked");
         this.pandoraObject._onDoubleClicked();
     }
 
-    onMouseWheel()
-    {
-        this.pandoraObject.emitSignal("mouseWheel");
-        this.pandoraObject._onMouseWheel();
-    }
-
+    /**
+     * Called once every time a mouse wheel is scrolled over this UIObject.
+     * Connected to the mouseWheel event from this UIObject's p5.Element.
+     * Serves as an emiter to the mouseWheel signal and calls the _onMouseWheel()
+     * callback.
+     * 
+     * @param {Object} event    contains data about the wheen scroll, with the deltaY
+     *                          and deltaX property, containing data about the vertical
+     *                          and horizontal scrolling, repsctively.
+     */
+    onMouseWheel(event)
+    {
+        this.pandoraObject.emitSignal("mouseWheel", event);
+        this.pandoraObject._onMouseWheel(event);
+    }
+
+    /**
+     * Called once every time a mouse button is released over this UIObject.
+     * Connected to the mouseReleased event from this UIObject's p5.Element.
+     * Serves as an emiter to the mouseReleased signal and calls the _onMouseReleased()
+     * callback.
+     */
     onMouseReleased()
     {
         this.pandoraObject.emitSignal("mouseReleased");
         this.pandoraObject._onMouseReleased();
     }
 
+    /**
+     * Called once every time a mouse button is pressed and released over this UIObject.
+     * Connected to the mouseClicked event from this UIObject's p5.Element.
+     * Serves as an emiter to the mouseClicked signal and calls the _onMouseClicked()
+     * callback.
+     */
     onMouseClicked()
     {
         this.pandoraObject.emitSignal("mouseClicked");
         this.pandoraObject._onMouseClicked();
     }
 
+    /**
+     * Called once everty time a mouse moves over this UIObject.
+     * Connected to the mouseMoved event from this UIObject's p5.Element.
+     * Serves as an emiter to the mouseMoved signal and calls the _onMouseMoved()
+     * callback.
+     */
     onMouseMoved()
     {
         this.pandoraObject.emitSignal("mouseMoved");
         this.pandoraObject._onMouseMoved();
     }
 
+    /**
+     * Called once every time a mouse moves onto this UIObject.
+     * Connected to the mouseOver event from this UIObject's p5.Element.
+     * Serves as an emiter to the mouseOver signal and calls the _onMouseOver()
+     * callback.
+     */
     onMouseOver()
     {
         this.pandoraObject.emitSignal("mouseOver");
         this.pandoraObject._onMouseOver();
     }
 
+    /**
+     * Called once every time a mouse moves off the UIObject.
+     * Connected to the mouseOut event from this UIObject's p5.Element.
+     * Serves as an emiter to the mouseOut signal and calls the _onMouseOut()
+     * callback.
+     */
     onMouseOut()
     {
         this.pandoraObject.emitSignal("mouseOut");
         this.pandoraObject._onMouseOut();
     }
 
+    /**
+     * Called once every time a touch is registered over this UIObject.
+     * Connected to the touchStarted event from this UIObject's p5.Element.
+     * Serves as an emiter to the touchStarted signal and calls the _onTouchStarted()
+     * callback.
+     */
     onTouchStarted()
     {
         this.pandoraObject.emitSignal("touchStarted");
         this.pandoraObject._onTouchStarted();
     }
 
+    /**
+     * Called once every time a touch move is registered over this UIObject.
+     * Connected to the touchMoved event from this UIObject's p5.Element.
+     * Serves as an emiter to the touchMoved signal and calls the _onTouchMoved()
+     * callback.
+     */
     onTouchMoved()
     {
         this.pandoraObject.emitSignal("touchMoved");
         this.pandoraObject._onTouchMoved();
     }
 
+    /**
+     * Called once every time a touch is registered over this UIObject.
+     * Connected to the touchEnded event from this UIObject's p5.Element.
+     * Serves as an emiter to the touchEnded signal and calls the _onTouchEnded()
+     * callback.
+     */
     onTouchEnded()
     {
         this.pandoraObject.emitSignal("touchEnded");
         this.pandoraObject._onTouchEnded();
     }
 
+    /**
+     * Called once every time a file is dragged over this UIObject's area.
+     * Connected to the dragOver event from this UIObject's p5.Element.
+     * Serves as an emiter to the dragOver signal and calls the _onDragOver()
+     * callback.
+     */
     onDragOver()
     {
         this.pandoraObject.emitSignal("dragOver");
         this.pandoraObject._onDragOver();
     }
 
+    /**
+     * Called once every time a dragged file leaves tis UIObject's area.
+     * Connected to the dragLeave event from this UIObject's p5.Element.
+     * Serves as an emiter to the dragLeave signal and calls the _onDragLeave()
+     * callback.
+     */
     onDragLeave()
     {
         this.pandoraObject.emitSignal("dragLeave");
         this.pandoraObject._onDragLeave();
     }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse button is pressed over this UIObject.
+     */
+    _onMousePressed()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse button in pressed twice over this UIObject.
+     */
+    _onDoubleClicked()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse wheel is scrolled over this UIObject.
+     * 
+     * @param {Object} event    contains data about the wheen scroll, with the deltaY
+     *                          and deltaX property, containing data about the vertical
+     *                          and horizontal scrolling, repsctively.
+     */
+    _onMouseWheel(event)
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse button is released over this UIObject.
+     */
+    _onMouseReleased()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse button is pressed and released over this UIObject.
+     */
+    _onMouseClicked()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once everty time a mouse moves over this UIObject.
+     */
+    _onMouseMoved()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse moves onto this UIObject.
+     */
+    _onMouseOver()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a mouse moves off the UIObject.
+     */
+    _onMouseOut()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a touch is registered over this UIObject.
+     */
+    _onTouchStarted()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a touch move is registered over this UIObject.
+     */
+    _onTouchMoved()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a touch is registered over this UIObject.
+     */
+    _onTouchEnded()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a file is dragged over this UIObject's area.
+     */
+    _onDragOver()
+    {
+
+    }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time a dragged file leaves tis UIObject's area.
+     */
+    _onDragLeave()
+    {
+
+    }
 }

pandora/handlers/AssetHandler.js

@@ -56,8 +56,8 @@ const AssetHandler = {
      * 
      * @param {String} name name of the requested TextureRes.
      * 
-     * @returns reference to the first loaded TextureRes whose name matches
-     *          the parameter, or null if no TextureRes matches the name.
+     * @returns {TextureRes}    reference to the first loaded TextureRes whose name matches
+     *                          the parameter, or null if no TextureRes matches the name.
      */
     getTextureByName: function(name)
     {
@@ -77,8 +77,8 @@ const AssetHandler = {
      * @param {String} name name of the TextureRes that holds the desired
      *                      p5.Image.
      * 
-     * @returns p5.Image held by the first loaded TextureRes whose name
-     *          matches the parameter, or null if no TextureRes matches the name.
+     * @returns {p5.Image}  p5.Image held by the first loaded TextureRes whose name
+     *                      matches the parameter, or null if no TextureRes matches the name.
      */
     getP5ImageByName: function(name)
     {
@@ -112,8 +112,8 @@ const AssetHandler = {
      * 
      * @param {String} name name of the requested AudioRes.
      * 
-     * @returns reference to the first loaded AudioRes whose name matches
-     *          the parameter, or null if no AudioRes matches the name.
+     * @returns {AudioRes}  reference to the first loaded AudioRes whose name matches
+     *                      the parameter, or null if no AudioRes matches the name.
      */
     getAudioByName: function(name)
     {
@@ -133,8 +133,8 @@ const AssetHandler = {
      * @param {String} name name of the AudioRes that holds the desired
      *                      p5.Audio.
      * 
-     * @returns p5.Audio held by the first loaded AudioRes whose name
-     *          matches the parameter, or null if no AudioRes matches the name.
+     * @returns {p5.Audio}  p5.Audio held by the first loaded AudioRes whose name
+     *                      matches the parameter, or null if no AudioRes matches the name.
      */
     getP5AudioByName: function(name)
     {
@@ -172,8 +172,8 @@ const AssetHandler = {
      * 
      * @param {String} name name of the requested FontRes.
      * 
-     * @returns reference to the first loaded FontRes whose name matches
-     *          the parameter, or null if no FontRes matches the name.
+     * @returns {FontRes}   reference to the first loaded FontRes whose name matches
+     *                      the parameter, or null if no FontRes matches the name.
      */
     getFontByName: function(name)
     {
@@ -193,8 +193,8 @@ const AssetHandler = {
      * @param {String} name name of the FontRes that holds the desired
      *                      p5.Font.
      * 
-     * @returns p5.Font held by the first loaded FontRes whose name
-     *          matches the parameter, or null if no FontRes matches the name.
+     * @returns {p5.Font}   p5.Font held by the first loaded FontRes whose name
+     *                      matches the parameter, or null if no FontRes matches the name.
      */
     getP5FontByName: function(name)
     {