Add particles docs

Author: samme

src/gameobjects/particles/EmitterOp.js

@@ -11,26 +11,95 @@ var GetFastValue = require('../../utils/object/GetFastValue');
 var Wrap = require('../../math/Wrap');
 
 /**
- * The returned value sets what the property will be at the START of the particles life, on emit.
+ * The returned value sets what the property will be at the START of the particle's life, on emit.
  * @callback EmitterOpOnEmitCallback
  *
- * @param {Phaser.GameObjects.Particles.Particle} particle - [description]
- * @param {string} key - [description]
- * @param {number} value - [description]
+ * @param {Phaser.GameObjects.Particles.Particle} particle - The particle.
+ * @param {string} key - The name of the property.
+ * @param {number} value - The current value of the property.
  *
- * @return {number} [description]
+ * @return {number} The new value of the property.
  */
 
 /**
- * The returned value updates the property for the duration of the particles life.
+ * The returned value updates the property for the duration of the particle's life.
  * @callback EmitterOpOnUpdateCallback
  *
- * @param {Phaser.GameObjects.Particles.Particle} particle - [description]
- * @param {string} key - [description]
- * @param {float} t - The T value (between 0 and 1)
- * @param {number} value - [description]
+ * @param {Phaser.GameObjects.Particles.Particle} particle - The particle.
+ * @param {string} key - The name of the property.
+ * @param {float} t - The normalized lifetime of the particle, between 0 (start) and 1 (end).
+ * @param {number} value - The current value of the property.
+ *
+ * @return {number} The new value of the property.
+ */
+
+/**
+ * Defines a value or an operation yielding a value, setting what a particle property will be at the START of the particle's life, on emit.
+ * @typedef {float|float[]|EmitterOpOnEmitCallback|EmitterOpRandomConfig|EmitterOpRandomMinMaxConfig|EmitterOpRandomStartEndConfig|EmitterOpSteppedConfig|EmitterOpCustomEmitConfig} EmitterOpEmitConfig
+ *
+ * @see Phaser.GameObjects.Particles.Particle#fire
+ */
+
+/**
+ * Defines an operation yielding a value, updating a particle property for the duration of the particle's life.
+ * @typedef {EmitterOpOnUpdateCallback|EmitterOpEaseConfig|EmitterOpCustomUpdateConfig} EmitterOpUpdateConfig
+ *
+ * @see Phaser.GameObjects.Particles.Particle#update
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomConfig
+ *
+ * @property {float[]} random - The minimum and maximum values, as [min, max].
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomMinMaxConfig
+ *
+ * @property {float} min - The minimum value.
+ * @property {float} max - The maximum value.
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomStartEndConfig
+ *
+ * @property {float} start - The starting value.
+ * @property {float} end - The ending value.
+ * @property {boolean} random - If false, this becomes {@link EmitterOpEaseConfig}.
+ */
+
+/**
+ * Defines an operation yielding a value incremented continuously across a range.
+ * @typedef {object} EmitterOpEaseConfig
+ *
+ * @property {float} start - The starting value.
+ * @property {float} end - The ending value.
+ * @property {string} [ease='Linear'] - The name of the easing function.
+ */
+
+/**
+ * Defines an operation yielding a value incremented by steps across a range.
+ * @typedef {object} EmitterOpSteppedConfig
  *
- * @return {number} [description]
+ * @property {number} start - The starting value.
+ * @property {number} end - The ending value.
+ * @property {number} steps - The number of steps between start and end.
+ */
+
+/**
+ * @typedef {object} EmitterOpCustomEmitConfig
+ *
+ * @property {EmitterOpOnEmitCallback} onEmit - [description]
+ */
+
+/**
+ * @typedef {object} EmitterOpCustomUpdateConfig
+ *
+ * @property {EmitterOpOnEmitCallback} [onEmit] - [description]
+ * @property {EmitterOpOnUpdateCallback} onUpdate - [description]
  */
 
 /**
@@ -247,7 +316,7 @@ var EmitterOp = new Class({
             //  x: 400
 
             this.onEmit = this.staticValueEmit;
-            this.onUpdate = this.staticValueUpdate;
+            this.onUpdate = this.staticValueUpdate; // How?
         }
         else if (Array.isArray(value))
         {
@@ -327,6 +396,7 @@ var EmitterOp = new Class({
 
                 //  x: { start: 100, end: 400, [ ease: 'Linear' ] }
 
+
                 var easeType = this.has(value, 'ease') ? value.ease : 'Linear';
 
                 this.ease = GetEaseFunction(easeType);
@@ -336,6 +406,9 @@ var EmitterOp = new Class({
                     this.onEmit = this.easedValueEmit;
                 }
 
+                //  BUG: alpha, rotate, scaleX, scaleY, or tint are eased here if {min, max} is given.
+                //  Probably this branch should exclude isRandom entirely.
+
                 this.onUpdate = this.easeValueUpdate;
             }
         }

src/gameobjects/particles/Particle.js

@@ -10,7 +10,8 @@ var DistanceBetween = require('../../math/distance/DistanceBetween');
 
 /**
  * @classdesc
- * [description]
+ * A Particle is a simple Game Object controlled by a Particle Emitter and Manager, and rendered by the Manager.
+ * It uses its own lightweight physics system, and can interact only with its Emitter's bounds and zones.
  *
  * @class Particle
  * @memberOf Phaser.GameObjects.Particles
@@ -37,7 +38,7 @@ var Particle = new Class({
         this.emitter = emitter;
 
         /**
-         * [description]
+         * The texture frame used to render this Particle.
          *
          * @name Phaser.GameObjects.Particles.Particle#frame
          * @type {Phaser.Textures.Frame}
@@ -47,7 +48,7 @@ var Particle = new Class({
         this.frame = null;
 
         /**
-         * [description]
+         * The position of this Particle within its Emitter's particle pool.
          *
          * @name Phaser.GameObjects.Particles.Particle#index
          * @type {number}
@@ -207,7 +208,7 @@ var Particle = new Class({
         this.tint = 0xffffffff;
 
         /**
-         * [description]
+         * The full color of this Particle, computed from its alpha and tint.
          *
          * @name Phaser.GameObjects.Particles.Particle#color
          * @type {number}
@@ -246,7 +247,7 @@ var Particle = new Class({
         this.delayCurrent = 0;
 
         /**
-         * The normalized lifespan T value.
+         * The normalized lifespan T value, where 0 is the start and 1 is the end.
          *
          * @name Phaser.GameObjects.Particles.Particle#lifeT
          * @type {float}
@@ -405,7 +406,7 @@ var Particle = new Class({
      * @param {Phaser.GameObjects.Particles.ParticleEmitter} emitter - The Emitter that is updating this Particle.
      * @param {number} delta - The delta time in ms.
      * @param {float} step - The delta value divided by 1000.
-     * @param {array} processors - [description]
+     * @param {array} processors - Particle processors (gravity wells).
      */
     computeVelocity: function (emitter, delta, step, processors)
     {