Docs for Phaser.Curves.Curve and Phaser.Curves.Path

And whitespace

Author: samme

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