Documentation fixes

src/anim/anim_animation.js

@@ -6,6 +6,11 @@ pc.extend(pc, function () {
         this.scale = scale;
     };
 
+    /**
+     * @name pc.Node
+     * @class  A node has a name and contains an array of keyframes.
+     * @returns {pc.Node} A new pc.Node.
+     */
     var Node = function Node() {
         this._name = "";
         this._keys = [];
@@ -15,7 +20,7 @@ pc.extend(pc, function () {
      * @name pc.Animation
      * @class An animation is a sequence of keyframe arrays which map to the nodes of a skeletal hierarchy.
      * It controls how the nodes of the hierarchy are transformed over time.
-     * @description Returns a new pc.Animation object.
+     * @returns {pc.Animation} A new pc.Animation object.
      */
     var Animation = function Animation() {
         this._name = "";
@@ -49,7 +54,9 @@ pc.extend(pc, function () {
     /**
      * @function
      * @name pc.Animation#getNode
-     * @returns {pc.Node} The node
+     * @description Gets a pc.Node by name
+     * @param {string} name The name of the pc.Node
+     * @returns {pc.Node} The pc.Node with the specified name
      * @author Will Eastcott
      */
     Animation.prototype.getNode = function (name) {
@@ -59,7 +66,8 @@ pc.extend(pc, function () {
     /**
      * @function
      * @name pc.Animation#getNodes
-     * @returns {Array} The nodes
+     * @description Gets the pc.Nodes of this pc.Animation
+     * @returns {[pc.Node]} An array of nodes.
      * @author Will Eastcott
      */
     Animation.prototype.getNodes = function () {
@@ -81,7 +89,7 @@ pc.extend(pc, function () {
      * @function
      * @name pc.Animation#setName
      * @description Sets the human-readable name of the specified animation.
-     * @param {number} name The new name for the animation.
+     * @param {string} name The new name for the animation.
      * @author Will Eastcott
      */
     Animation.prototype.setName = function (name) {
@@ -90,9 +98,9 @@ pc.extend(pc, function () {
 
     /**
      * @function
-     * @name pc.Animation#setNode
-     * @param {String} name
-     * @param {pc.Node} node
+     * @name pc.Animation#addNode
+     * @description Adds a node the the internal nodes array.
+     * @param {pc.Node} node The node to add.
      * @author Will Eastcott
      */
     Animation.prototype.addNode = function (node) {

src/anim/anim_skeleton.js

@@ -25,7 +25,8 @@ pc.extend(pc, function () {
 
     /**
      * @name pc.Skeleton
-     * @class A skeleton.
+     * @class Represents a skeleton used to play animations.
+     * @param {pc.GraphNode} graph The root pc.GraphNode of the skeleton.
      */
     var Skeleton = function Skeleton(graph) {
         this._animation = null;

src/asset/asset_asset.js

@@ -13,19 +13,21 @@ pc.extend(pc, function () {
     *
     * See the {@link pc.AssetRegistry} for details on loading resources from assets.
     * @property {String} name The name of the asset
-    * @property {String} type The type of the asset. One of ["animation", "audio", "image", "json", "material", "model", "text", "texture"]
+    * @property {Number} id The asset id
+    * @property {String} type The type of the asset. One of ["animation", "audio", "image", "json", "material", "model", "text", "texture", "cubemap"]
     * @property {Object} file The file details or null if no file
     * @property {String} [file.url] The URL of the resource file that contains the asset data
     * @property {String} [file.filename] The filename of the resource file
     * @property {Number} [file.size] The size of the resource file
     * @property {String} [file.hash] The MD5 hash of the resource file data and the Asset data field.
     * @property {Object} data JSON data that contains either the complete resource data (e.g. in the case of a material) or additional data (e.g. in the case of a model it contains mappings from mesh to material)
     * @property {Object} resource A reference to the resource when the asset is loaded. e.g. a {@link pc.Texture} or a {@link pc.Model}
+    * @property {Array} resources A reference to the resources of the asset when it's loaded (an asset can hold more runtime resources than one e.g. cubemaps)
     * @property {Boolean} preload If true the asset will be loaded during the preload phase of application set up.
     * @property {Boolean} loaded True if the resource is loaded e.g. if asset.resource is not null
     * @constructor Create a new Asset record. Generally, Assets are created in the loading process and you won't need to create them by hand.
     * @param {String} name A non-unique but human-readable name which can be later used to retrieve the asset.
-    * @param {String} type Type of asset. One of ["animation", "audio", "image", "json", "material", "model", "text", "texture"]
+    * @param {String} type Type of asset. One of ["animation", "audio", "image", "json", "material", "model", "text", "texture", "cubemap"]
     * @param {Object} file Details about the file the asset is made from. At the least must contain the 'url' field. For assets that don't contain file data use null.
     * @example
     * var file = {
@@ -110,7 +112,7 @@ pc.extend(pc, function () {
         /**
         * @function
         * @name pc.Asset#unload
-        * @description Mark asset as unloaded and delte reference to resource
+        * @description Mark asset as unloaded and delete reference to resource
         * @example
         * var asset = app.assets.find("My Asset");
         * asset.unloade();

src/asset/asset_registry.js

@@ -23,6 +23,7 @@ pc.extend(pc, function () {
         * @name pc.AssetRegistry#list
         * @description Create a filtered list of assets from the registry
         * @param {Object} filters Properties to filter on, currently supports: 'preload: true|false'
+        * @returns {[pc.Asset]} The filtered list of assets.
         */
         list: function (filters) {
             filters = filters || {};
@@ -94,6 +95,7 @@ pc.extend(pc, function () {
         * @name pc.AssetRegistry#get
         * @description Retrieve an asset from the registry by its id field
         * @param {int} id the id of the asset to get
+        * @returns {pc.Asset} The asset
         * @example
         * var asset = app.assets.get(100);
         */
@@ -107,6 +109,7 @@ pc.extend(pc, function () {
         * @name pc.AssetRegistry#getByUrl
         * @description Retrieve an asset from the registry by it's file's URL field
         * @param {string} url The url of the asset to get
+        * @returns {pc.Asset} The asset
         * @example
         * var asset = app.assets.getByUrl("../path/to/image.jpg");
         */

src/core/core_bind.js

@@ -1,26 +1,27 @@
 /**
+ * @private
  * Shim to add the Function.bind() method to the Function type. This may be required for Opera and Safari.
- * https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function/bind
+ * https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function/bind
  */
-if (!Function.prototype.bind) {  
-  
-  Function.prototype.bind = function (oThis) {  
-  
-    if (typeof this !== "function") // closest thing possible to the ECMAScript 5 internal IsCallable function  
-      throw new TypeError("Function.prototype.bind - what is trying to be fBound is not callable");  
-  
-    var aArgs = Array.prototype.slice.call(arguments, 1),   
-        fToBind = this,   
-        fNOP = function () {},  
-        fBound = function () {  
-          return fToBind.apply(this instanceof fNOP ? this : oThis || window, aArgs.concat(Array.prototype.slice.call(arguments)));      
-        };  
-  
-    fNOP.prototype = this.prototype;  
-    fBound.prototype = new fNOP();  
-  
-    return fBound;  
-  
-  };  
-  
-} 
+if (!Function.prototype.bind) {
+
+  Function.prototype.bind = function (oThis) {
+
+    if (typeof this !== "function") // closest thing possible to the ECMAScript 5 internal IsCallable function
+      throw new TypeError("Function.prototype.bind - what is trying to be fBound is not callable");
+
+    var aArgs = Array.prototype.slice.call(arguments, 1),
+        fToBind = this,
+        fNOP = function () {},
+        fBound = function () {
+          return fToBind.apply(this instanceof fNOP ? this : oThis || window, aArgs.concat(Array.prototype.slice.call(arguments)));
+        };
+
+    fNOP.prototype = this.prototype;
+    fBound.prototype = new fNOP();
+
+    return fBound;
+
+  };
+
+}

src/core/core_core.js

@@ -129,6 +129,7 @@ var pc = {
         /**
          * Return true if the Object is not undefined
          * @param {Object} o The Object to test
+         * @returns {Boolean} True if the Object is not undefined
          * @function
          * @name pc.isDefined
          */

src/framework/components/animation/animation_component.js

@@ -11,7 +11,7 @@ pc.extend(pc, function () {
     * @property {Number} speed Speed multiplier for animation play back speed. 1.0 is playback at normal speed, 0.0 pauses the animation
     * @property {Boolean} loop If true the animation will restart from the beginning when it reaches the end
     * @property {Boolean} activate If true the first animation asset will begin playing when the Pack is loaded
-    * @property {Number[]} assets The array of animation assets
+    * @property {[pc.Asset]} assets The array of animation assets - can also be an array of asset ids.
     */
     var AnimationComponent = function (system, entity) {
         // Handle changes to the 'animations' value

src/framework/components/audiosource/audiosource_component.js

@@ -8,7 +8,7 @@ pc.extend(pc, function () {
      * @param {pc.Entity} entity The entity that the Component is attached to
      * @extends pc.Component
      * @property {Boolean} enabled If false no audio will be played
-     * @property {Array} assets The list of audio assets
+     * @property {[pc.Asset]} assets The list of audio assets - can also be an array of asset ids.
      * @property {Boolean} activate If true the audio will begin playing as soon as the Pack is loaded
      * @property {Number} volume The volume modifier to play the audio with. In range 0-1.
      * @property {Number} pitch The pitch modifier to play the audio with. Must be larger than 0.01

src/framework/components/camera/camera_system.js

@@ -4,7 +4,7 @@ pc.extend(pc, function () {
      * @class Used to add and remove {@link pc.CameraComponent}s from Entities. It also holds an
      * array of all active cameras.
      * @constructor Create a new CameraComponentSystem
-     * @param {Object} app
+     * @param {pc.Application} app The Application
      * @extends pc.ComponentSystem
      */
     var CameraComponentSystem = function (app) {

src/framework/components/model/model_component.js

@@ -17,7 +17,7 @@ pc.extend(pc, function () {
      *     <li>sphere: The component will render a sphere</li>
      * </ul>
      * @property {Boolean} enabled Enable or disable rendering of the Model
-     * @property {Number} asset The id of the asset for the model (only applies to models of type 'asset')
+     * @property {pc.Asset} asset The asset for the model (only applies to models of type 'asset') - can also be an asset id.
      * @property {Boolean} castShadows If true, this model will cast shadows for lights that have shadow casting enabled.
      * @property {Boolean} receiveShadows If true, shadows will be cast on this model
      * @property {Number} materialAsset The material {@link pc.Asset} that will be used to render the model (not used on models of type 'asset')

src/framework/components/model/model_system.js

@@ -4,7 +4,7 @@ pc.extend(pc, function () {
      * @constructor Create a new ModelComponentSystem
      * @class Allows an Entity to render a model or a primitive shape like a box,
      * capsule, sphere, cylinder, cone etc.
-     * @param {Object} app
+     * @param {pc.Application} app The Application.
      * @extends pc.ComponentSystem
      */
     var ModelComponentSystem = function ModelComponentSystem (app) {

src/framework/components/particlesystem/particlesystem_system.js

@@ -1,5 +1,12 @@
 pc.extend(pc, function() {
 
+   /**
+     * @name pc.ParticleSystemComponentSystem
+     * @constructor Create a new ParticleSystemComponentSystem
+     * @class Allows an Entity to render a particle system
+     * @param {pc.Application} app The Application.
+     * @extends pc.ComponentSystem
+     */
     var ParticleSystemComponentSystem = function ParticleSystemComponentSystem(app) {
         this.id = 'particlesystem';
         this.description = "Updates and renders particle system in the scene.";

src/framework/components/physics/collision/collision_component.js

@@ -62,7 +62,7 @@ pc.extend(pc, function () {
      * @property {Number} radius The radius of the sphere, capsule or cylinder-shaped collision volumes. Defaults to 0.5
      * @property {Number} axis The local space axis with which the capsule or cylinder-shaped collision volume's length is aligned. 0 for X, 1 for Y and 2 for Z. Defaults to 1 (Y-axis).
      * @property {Number} height The total height of the capsule or cylinder-shaped collision volume from tip to tip. Defaults to 2.
-     * @property {Number} asset The id of the asset for the model of the mesh collision volume.
+     * @property {pc.Asset} asset The asset for the model of the mesh collision volume - can also be an asset id.
      * @property {pc.Model} model The model that is added to the scene graph for the mesh collision volume.
      * @extends pc.Component
      */

src/framework/components/physics/collision/collision_trigger.js

@@ -5,7 +5,7 @@ pc.extend(pc, function () {
     /**
     * @private
     * @name pc.Trigger
-    * @description Creates a trigger object used to create internal physics objects that interact with
+    * @class Creates a trigger object used to create internal physics objects that interact with
     * rigid bodies and trigger collision events with no collision response
     * @param {pc.Application} app The running {pc.Application}
     * @param {pc.Component} component The component for which the trigger will be created

src/framework/components/pick/pick_component.js

@@ -4,8 +4,8 @@ pc.extend(pc, function () {
      * @name pc.PickComponent
      * @constructor Create a new PickComponent
      * @class Allows an Entity to be picked from the scene using a pc.picking.Picker Object
-    * @param {pc.PickComponentSystem} system The ComponentSystem that created this Component
-    * @param {pc.Entity} entity The Entity that this Component is attached to.
+     * @param {pc.PickComponentSystem} system The ComponentSystem that created this Component
+     * @param {pc.Entity} entity The Entity that this Component is attached to.
      * @extends pc.Component
      */
     var PickComponent = function PickComponent(system, entity) {

src/framework/components/pick/pick_system.js

@@ -4,7 +4,7 @@ pc.extend(pc, function () {
      * @name pc.PickComponentSystem
      * @constructor Create a new PickComponentSystem
      * @class Allows an Entity to be picked from the scene using a pc.picking.Picker Object
-     * @param {Object} app
+     * @param {pc.Application} app The Application.
      * @extends pc.ComponentSystem
      */
     var PickComponentSystem = function PickComponentSystem(app) {

src/framework/components/script/script_component.js

@@ -15,7 +15,7 @@ pc.extend(pc, function () {
     * <li>fixedUpdate</li>
     * <li>postUpdate</li>
     * </ul>
-    * @property {Object[]} scripts An array of all the scripts to load. Each script object has this format:
+    * @property {Array} scripts An array of all the scripts to load. Each script object has this format:
     * {url: 'url.js', name: 'url', 'attributes': [attribute1, attribute2, ...]}
     */
 

src/framework/components/script/script_system.js

@@ -13,7 +13,8 @@ pc.extend(pc, function () {
      * @name pc.ScriptComponentSystem
      * @constructor Create a new ScriptComponentSystem
      * @class Allows scripts to be attached to an Entity and executed
-     * @param {Object} app
+     * @param {pc.Application} app The application
+     * @param {string} [prefix] An optional prefix that will be applied to all script URLs.
      * @extends pc.ComponentSystem
      */
     var ScriptComponentSystem = function ScriptComponentSystem(app, prefix) {

src/input/input_controller.js

@@ -326,6 +326,7 @@ pc.extend(pc, function () {
      * @name pc.Controller#wasPressed
      * @description Returns true if the action was enabled this since the last update
      * @param {String} action The name of the action
+     * @returns {Boolean} True if the action was enabled this since the last update
      */
     Controller.prototype.wasPressed = function (actionName) {
         if (!this._actions[actionName]) {

src/input/input_keyboard.js

@@ -4,7 +4,7 @@ pc.extend(pc, function(){
     * @class The KeyboardEvent is passed into all event callbacks from the {@link pc.Keyboard}. It corresponds to a key press or release.
     * @constructor Create a new KeyboardEvent
     * @param {pc.Keyboard} keyboard The keyboard object which is firing the event.
-    * @param {KeyboardEvent} event The original browser event that was fired.
+    * @param {pc.KeyboardEvent} event The original browser event that was fired.
     * @property {pc.KEY} key The keyCode of the key that has changed.
     * @property {DOMElement} element The element that fired the keyboard event.
     * @property {KeyboardEvent} event The original browser event which was fired.