Merge pull request phaserjs#4940 from samme/docs/misc-3

Docs for Curve, Path, ScenePlugin, BaseSoundManager

Author: photonstorm

src/curves/Curve.js

@@ -20,7 +20,7 @@ var Vector2 = require('../math/Vector2');
  * @constructor
  * @since 3.0.0
  *
- * @param {string} type - [description]
+ * @param {string} type - The curve type.
  */
 var Curve = new Class({
 
@@ -78,7 +78,7 @@ var Curve = new Class({
         this.needsUpdate = true;
 
         /**
-         * [description]
+         * For a curve on a Path, `false` means the Path will ignore this curve.
          *
          * @name Phaser.Curves.Curve#active
          * @type {boolean}
@@ -131,7 +131,7 @@ var Curve = new Class({
         //  So you can chain graphics calls
         return graphics.strokePoints(this.getPoints(pointsTotal));
     },
-    
+
     /**
      * Returns a Rectangle where the position and dimensions match the bounds of this Curve.
      *
@@ -187,7 +187,7 @@ var Curve = new Class({
     },
 
     /**
-     * [description]
+     * Get a point at the end of the curve.
      *
      * @method Phaser.Curves.Curve#getEndPoint
      * @since 3.0.0
@@ -209,7 +209,7 @@ var Curve = new Class({
      * @method Phaser.Curves.Curve#getLength
      * @since 3.0.0
      *
-     * @return {number} [description]
+     * @return {number} The total length of the curve.
      */
     getLength: function ()
     {
@@ -220,14 +220,22 @@ var Curve = new Class({
 
 
     /**
-     * Get list of cumulative segment lengths
+     * Get a list of cumulative segment lengths.
+     *
+     * These lengths are
+     *
+     * - [0] 0
+     * - [1] The first segment
+     * - [2] The first and second segment
+     * - ...
+     * - [divisions] All segments
      *
      * @method Phaser.Curves.Curve#getLengths
      * @since 3.0.0
      *
-     * @param {integer} [divisions] - [description]
+     * @param {integer} [divisions] - The number of divisions or segments.
      *
-     * @return {number[]} [description]
+     * @return {number[]} An array of cumulative lengths.
      */
     getLengths: function (divisions)
     {
@@ -268,17 +276,17 @@ var Curve = new Class({
     // - u [0 .. 1]
 
     /**
-     * [description]
+     * Get a point at a relative position on the curve, by arc length.
      *
      * @method Phaser.Curves.Curve#getPointAt
      * @since 3.0.0
      *
      * @generic {Phaser.Math.Vector2} O - [out,$return]
      *
-     * @param {number} u - [description]
-     * @param {Phaser.Math.Vector2} [out] - [description]
+     * @param {number} u - The relative position, [0..1].
+     * @param {Phaser.Math.Vector2} [out] - A point to store the result in.
      *
-     * @return {Phaser.Math.Vector2} [description]
+     * @return {Phaser.Math.Vector2} The point.
      */
     getPointAt: function (u, out)
     {
@@ -290,13 +298,23 @@ var Curve = new Class({
     // Get sequence of points using getPoint( t )
 
     /**
-     * [description]
+     * Get a sequence of evenly spaced points from the curve.
+     *
+     * You can pass `divisions`, `stepRate`, or neither.
+     *
+     * The number of divisions will be
+     *
+     * 1. `divisions`, if `divisions` > 0; or
+     * 2. `this.getLength / stepRate`, if `stepRate` > 0; or
+     * 3. `this.defaultDivisions`
+     *
+     * `1 + divisions` points will be returned.
      *
      * @method Phaser.Curves.Curve#getPoints
      * @since 3.0.0
      *
-     * @param {integer} divisions - The number of evenly spaced points from the curve to return. If falsy, step param will be used to calculate the number of points.
-     * @param {number} step - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive.     
+     * @param {integer} [divisions] - The number of divisions to make.
+     * @param {number} [stepRate] - The curve distance between points, implying `divisions`.
      * @param {(array|Phaser.Math.Vector2[])} [out] - An optional array to store the points in.
      *
      * @return {(array|Phaser.Math.Vector2[])} An array of Points from the curve.
@@ -327,16 +345,16 @@ var Curve = new Class({
     },
 
     /**
-     * [description]
+     * Get a random point from the curve.
      *
      * @method Phaser.Curves.Curve#getRandomPoint
      * @since 3.0.0
      *
      * @generic {Phaser.Math.Vector2} O - [out,$return]
      *
-     * @param {Phaser.Math.Vector2} [out] - [description]
+     * @param {Phaser.Math.Vector2} [out] - A point object to store the result in.
      *
-     * @return {Phaser.Math.Vector2} [description]
+     * @return {Phaser.Math.Vector2} The point.
      */
     getRandomPoint: function (out)
     {
@@ -348,16 +366,18 @@ var Curve = new Class({
     // Get sequence of points using getPointAt( u )
 
     /**
-     * [description]
+     * Get a sequence of equally spaced points (by arc distance) from the curve.
+     *
+     * `1 + divisions` points will be returned.
      *
      * @method Phaser.Curves.Curve#getSpacedPoints
      * @since 3.0.0
      *
-     * @param {integer} [divisions] - The number of evenly spaced points from the curve to return. If falsy, step param will be used to calculate the number of points.
-     * @param {number} [step] - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive.     
+     * @param {integer} [divisions=this.defaultDivisions] - The number of divisions to make.
+     * @param {number} [stepRate] - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive.
      * @param {(array|Phaser.Math.Vector2[])} [out] - An optional array to store the points in.
      *
-     * @return {Phaser.Math.Vector2[]} [description]
+     * @return {Phaser.Math.Vector2[]} An array of points.
      */
     getSpacedPoints: function (divisions, stepRate, out)
     {
@@ -387,16 +407,16 @@ var Curve = new Class({
     },
 
     /**
-     * [description]
+     * Get a point at the start of the curve.
      *
      * @method Phaser.Curves.Curve#getStartPoint
      * @since 3.0.0
      *
      * @generic {Phaser.Math.Vector2} O - [out,$return]
      *
-     * @param {Phaser.Math.Vector2} [out] - [description]
+     * @param {Phaser.Math.Vector2} [out] - A point to store the result in.
      *
-     * @return {Phaser.Math.Vector2} [description]
+     * @return {Phaser.Math.Vector2} The point.
      */
     getStartPoint: function (out)
     {
@@ -406,7 +426,7 @@ var Curve = new Class({
     },
 
     /**
-     * Returns a unit vector tangent at t
+     * Get a unit vector tangent at a relative position on the curve.
      * In case any sub curve does not implement its tangent derivation,
      * 2 points a small delta apart will be used to find its gradient
      * which seems to give a reasonable approximation
@@ -416,8 +436,8 @@ var Curve = new Class({
      *
      * @generic {Phaser.Math.Vector2} O - [out,$return]
      *
-     * @param {number} t - [description]
-     * @param {Phaser.Math.Vector2} [out] - [description]
+     * @param {number} t - The relative position on the curve, [0..1].
+     * @param {Phaser.Math.Vector2} [out] - A vector to store the result in.
      *
      * @return {Phaser.Math.Vector2} Vector approximating the tangent line at the point t (delta +/- 0.0001)
      */
@@ -448,17 +468,17 @@ var Curve = new Class({
     },
 
     /**
-     * [description]
+     * Get a unit vector tangent at a relative position on the curve, by arc length.
      *
      * @method Phaser.Curves.Curve#getTangentAt
      * @since 3.0.0
      *
      * @generic {Phaser.Math.Vector2} O - [out,$return]
      *
-     * @param {number} u - [description]
-     * @param {Phaser.Math.Vector2} [out] - [description]
+     * @param {number} u - The relative position on the curve, [0..1].
+     * @param {Phaser.Math.Vector2} [out] - A vector to store the result in.
      *
-     * @return {Phaser.Math.Vector2} [description]
+     * @return {Phaser.Math.Vector2} The tangent vector.
      */
     getTangentAt: function (u, out)
     {
@@ -573,10 +593,12 @@ var Curve = new Class({
     },
 
     /**
-     * [description]
+     * Calculate and cache the arc lengths.
      *
      * @method Phaser.Curves.Curve#updateArcLengths
      * @since 3.0.0
+     *
+     * @see Phaser.Curves.Curve#getLengths()
      */
     updateArcLengths: function ()
     {

src/curves/path/Path.js

@@ -569,14 +569,12 @@ var Path = new Class({
     },
 
     /**
-     * Returns the defined starting point of the Path.
-     *
-     * This is not necessarily equal to the starting point of the first Curve if it differs from {@link startPoint}.
+     * Get a sequence of points on the path.
      *
      * @method Phaser.Curves.Path#getPoints
      * @since 3.0.0
      *
-     * @param {integer} [divisions=12] - The number of points to divide the path in to.
+     * @param {integer} [divisions=12] - The number of divisions per resolution per curve.
      *
      * @return {Phaser.Math.Vector2[]} An array of Vector2 objects that containing the points along the Path.
      */
@@ -626,7 +624,7 @@ var Path = new Class({
 
     /**
      * Returns a randomly chosen point anywhere on the path. This follows the same rules as `getPoint` in that it may return a point on any Curve inside this path.
-     * 
+     *
      * When calling this method multiple times, the points are not guaranteed to be equally spaced spatially.
      *
      * @method Phaser.Curves.Path#getRandomPoint
@@ -647,7 +645,7 @@ var Path = new Class({
 
     /**
      * Divides this Path into a set of equally spaced points,
-     * 
+     *
      * The resulting points are equally spaced with respect to the points' position on the path, but not necessarily equally spaced spatially.
      *
      * @method Phaser.Curves.Path#getSpacedPoints
@@ -741,7 +739,7 @@ var Path = new Class({
 
     /**
      * Creates a "gap" in this path from the path's current end point to the given coordinates.
-     * 
+     *
      * After calling this function, this Path's end point will be equal to the given coordinates
      *
      * @method Phaser.Curves.Path#moveTo

src/scene/ScenePlugin.js

@@ -188,6 +188,8 @@ var ScenePlugin = new Class({
     /**
      * Shutdown this Scene and run the given one.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#start
      * @since 3.0.0
      *
@@ -209,6 +211,8 @@ var ScenePlugin = new Class({
     /**
      * Restarts this Scene.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#restart
      * @since 3.4.0
      *
@@ -444,6 +448,8 @@ var ScenePlugin = new Class({
     /**
      * Launch the given Scene and run it in parallel with this one.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#launch
      * @since 3.0.0
      *
@@ -465,6 +471,8 @@ var ScenePlugin = new Class({
     /**
      * Runs the given Scene, but does not change the state of this Scene.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * If the given Scene is paused, it will resume it. If sleeping, it will wake it.
      * If not running at all, it will be started.
      *
@@ -492,6 +500,8 @@ var ScenePlugin = new Class({
     /**
      * Pause the Scene - this stops the update step from happening but it still renders.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#pause
      * @since 3.0.0
      *
@@ -512,6 +522,8 @@ var ScenePlugin = new Class({
     /**
      * Resume the Scene - starts the update loop again.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#resume
      * @since 3.0.0
      *
@@ -532,6 +544,8 @@ var ScenePlugin = new Class({
     /**
      * Makes the Scene sleep (no update, no render) but doesn't shutdown.
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#sleep
      * @since 3.0.0
      *
@@ -552,6 +566,8 @@ var ScenePlugin = new Class({
     /**
      * Makes the Scene wake-up (starts update and render)
      *
+     * This will happen at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#wake
      * @since 3.0.0
      *
@@ -571,11 +587,8 @@ var ScenePlugin = new Class({
 
     /**
      * Makes this Scene sleep then starts the Scene given.
-     * 
-     * No checks are made to see if an instance of the given Scene is already running.
-     * Because Scenes in Phaser are non-exclusive, you are allowed to run multiple
-     * instances of them _at the same time_. This means, calling this function
-     * may launch another instance of the requested Scene if it's already running.
+     *
+     * This will happen at the next Scene Manager update, not immediately.
      *
      * @method Phaser.Scenes.ScenePlugin#switch
      * @since 3.0.0
@@ -597,6 +610,8 @@ var ScenePlugin = new Class({
     /**
      * Shutdown the Scene, clearing display list, timers, etc.
      *
+     * This happens at the next Scene Manager update, not immediately.
+     *
      * @method Phaser.Scenes.ScenePlugin#stop
      * @since 3.0.0
      *
@@ -814,7 +829,7 @@ var ScenePlugin = new Class({
      * The Scene is removed from the local scenes array, it's key is cleared from the keys
      * cache and Scene.Systems.destroy is then called on it.
      *
-     * If the SceneManager is processing the Scenes when this method is called it wil
+     * If the SceneManager is processing the Scenes when this method is called it will
      * queue the operation for the next update sequence.
      *
      * @method Phaser.Scenes.ScenePlugin#remove

src/sound/BaseSoundManager.js

@@ -227,8 +227,9 @@ var BaseSoundManager = new Class({
     },
 
     /**
-     * Enables playing sound on the fly without the need to keep a reference to it.
-     * Sound will auto destroy once its playback ends.
+     * Adds a new sound to the sound manager and plays it.
+     * The sound will be automatically removed (destroyed) once playback ends.
+     * This lets you play a new sound on the fly without the need to keep a reference to it.
      *
      * @method Phaser.Sound.BaseSoundManager#play
      * @listens Phaser.Sound.Events#COMPLETE