From bee0a96542880f5486006eeb3d46f83923eb5106 Mon Sep 17 00:00:00 2001 From: samme Date: Fri, 3 Jan 2020 13:34:05 -0800 Subject: [PATCH] Docs for Phaser.Curves.Curve and Phaser.Curves.Path And whitespace --- src/curves/Curve.js | 88 +++++++++++++++++++++++++---------------- src/curves/path/Path.js | 12 +++--- 2 files changed, 60 insertions(+), 40 deletions(-) diff --git a/src/curves/Curve.js b/src/curves/Curve.js index 36b8023b4..4d79a8adb 100644 --- a/src/curves/Curve.js +++ b/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 () { diff --git a/src/curves/path/Path.js b/src/curves/path/Path.js index eec47c28c..6cdc5e668 100644 --- a/src/curves/path/Path.js +++ b/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