diff --git a/src/math/p5.Vector.js b/src/math/p5.Vector.js index 914d5f5b87..d7ba19b7e5 100644 --- a/src/math/p5.Vector.js +++ b/src/math/p5.Vector.js @@ -11,7 +11,7 @@ import * as constants from '../core/constants'; * A class to describe a two or three-dimensional vector, specifically * a Euclidean (also known as geometric) vector. A vector is an entity * that has both magnitude and direction. The datatype, however, stores - * the components of the vector (x, y for 2D, and x, y, z for 3D). The magnitude + * the components of the vector (`x`, `y` for 2D; or `x`, `y`, `z` for 3D). The magnitude * and direction can be accessed via the methods p5.Vector.mag() and heading(). * * In many of the p5.js examples, you will see p5.Vector used to describe a @@ -84,8 +84,8 @@ p5.Vector = function Vector() { }; /** - * Returns a string representation of a vector v by calling String(v) - * or v.toString(). This method is useful for logging vectors in the + * Returns a string representation of a vector `v` by calling `String(v)` + * or `v.toString()`. This method is useful for logging vectors in the * console. * @method toString * @return {String} @@ -134,12 +134,12 @@ p5.Vector.prototype.toString = function p5VectorToString() { }; /** - * Sets the x, y, and z component of the vector using two or three separate + * Sets the `x`, `y`, and `z` components of the vector using two or three separate * variables, the data from a p5.Vector, or the values from a float array. * @method set - * @param {Number} [x] the x component of the vector - * @param {Number} [y] the y component of the vector - * @param {Number} [z] the z component of the vector + * @param {Number} [x] The x component of the vector + * @param {Number} [y] The y component of the vector + * @param {Number} [z] The z component of the vector * @chainable * @example *
@@ -194,7 +194,7 @@ p5.Vector.prototype.toString = function p5VectorToString() { */ /** * @method set - * @param {p5.Vector|Number[]} value the vector to set + * @param {p5.Vector|Number[]} value The vector to set * @chainable */ p5.Vector.prototype.set = function set(x, y, z) { @@ -220,7 +220,7 @@ p5.Vector.prototype.set = function set(x, y, z) { * Gets a copy of the vector, returns a p5.Vector object. * * @method copy - * @return {p5.Vector} the copy of the p5.Vector object + * @return {p5.Vector} A copy of the p5.Vector object * @example *
* @@ -246,16 +246,16 @@ p5.Vector.prototype.copy = function copy() { }; /** - * Adds x, y, and z components to a vector, adds one vector to another, or + * Adds `x`, `y`, and `z` components to a vector, adds one vector to another, or * adds two independent vectors together. The version of the method that adds * two vectors together is a static method and returns a p5.Vector, the others * act directly on the vector. Additionally, you may provide arguments to this method as an array. * See the examples for more context. * * @method add - * @param {Number} x the x component of the vector to be added - * @param {Number} [y] the y component of the vector to be added - * @param {Number} [z] the z component of the vector to be added + * @param {Number} x The x component of the vector to be added + * @param {Number} [y] The y component of the vector to be added + * @param {Number} [z] The z component of the vector to be added * @chainable * @example *
@@ -324,7 +324,7 @@ p5.Vector.prototype.copy = function copy() { */ /** * @method add - * @param {p5.Vector|Number[]} value the vector to add + * @param {p5.Vector|Number[]} value The vector to add * @chainable */ p5.Vector.prototype.add = function add(x, y, z) { @@ -374,9 +374,9 @@ const calculateRemainder3D = function(xComponent, yComponent, zComponent) { * See examples for more context. * * @method rem - * @param {Number} x the x component of divisor vector - * @param {Number} y the y component of divisor vector - * @param {Number} z the z component of divisor vector + * @param {Number} x The x component of divisor vector + * @param {Number} y The y component of divisor vector + * @param {Number} z The z component of divisor vector * @chainable * @example *
@@ -400,7 +400,7 @@ const calculateRemainder3D = function(xComponent, yComponent, zComponent) { */ /** * @method rem - * @param {p5.Vector | Number[]} value divisor vector + * @param {p5.Vector | Number[]} value The divisor vector * @chainable */ p5.Vector.prototype.rem = function rem(x, y, z) { @@ -459,16 +459,16 @@ p5.Vector.prototype.rem = function rem(x, y, z) { }; /** - * Subtracts x, y, and z components from a vector, subtracts one vector from + * Subtracts `x`, `y`, and `z` components from a vector, subtracts one vector from * another, or subtracts two independent vectors. The version of the method * that subtracts two vectors is a static method and returns a p5.Vector, the * others act directly on the vector. Additionally, you may provide arguments to this method as an array. * See the examples for more context. * * @method sub - * @param {Number} x the x component of the vector to subtract - * @param {Number} [y] the y component of the vector to subtract - * @param {Number} [z] the z component of the vector to subtract + * @param {Number} x The x component of the vector to subtract + * @param {Number} [y] The y component of the vector to subtract + * @param {Number} [z] The z component of the vector to subtract * @chainable * @example *
@@ -560,13 +560,13 @@ p5.Vector.prototype.sub = function sub(x, y, z) { }; /** - * Multiplies the vector by a scalar, multiplies the x, y, and z components from a vector, or multiplies - * the x, y, and z components of two independent vectors. When multiplying a vector by a scalar, the x, y, - * and z components of the vector are all multiplied by the scalar. When multiplying a vector by a vector, - * the x, y, z components of both vectors are multiplied by each other - * (for example, with two vectors a and b: a.x * b.x, a.y * b.y, a.z * b.z). The static version of this method + * Multiplies the vector by a scalar, multiplies the `x`, `y`, and `z` components from a vector, or multiplies + * the `x`, `y`, and `z` components of two independent vectors. When multiplying a vector by a scalar, the `x`, `y`, + * and `z` components of the vector are all multiplied by the scalar. When multiplying a vector by a vector, + * the `x`, `y`, `z` components of both vectors are multiplied by each other + * (for example, with two vectors `a` and `b`: `a.x * b.x`, `a.y * b.y`, `a.z * b.z`). The static version of this method * creates a new p5.Vector while the non-static version acts on the vector - * directly. Additionally, you may provide arguments to this method as an array. + * directly. Additionally, you may provide arguments to this function as an array. * See the examples for more context. * * @method mult @@ -752,11 +752,12 @@ p5.Vector.prototype.mult = function mult(x, y, z) { }; /** - * Divides the vector by a scalar, divides a vector by the x, y, and z arguments, or divides the x, y, and - * z components of two vectors against each other. When dividing a vector by a scalar, the x, y, - * and z components of the vector are all divided by the scalar. When dividing a vector by a vector, - * the x, y, z components of the source vector are treated as the dividend, and the x, y, z components - * of the argument are treated as the divisor (for example with two vectors a and b: a.x / b.x, a.y / b.y, a.z / b.z). + * Divides the vector by a scalar, divides a vector by the `x`, `y`, and `z` arguments, or divides the `x`, `y`, and + * `z` components of two vectors against each other. When dividing a vector by a scalar, the `x`, `y`, + * and `z` components of the vector are all divided by the scalar. When dividing a vector by a vector, + * the `x`, `y`, `z` components of the source vector are treated as the dividend, and the `x`, `y`, `z` components + * of the argument is treated as the divisor. (For example, with two vectors + * `a` and `b`: `a.x / b.x`, `a.y / b.y`, `a.z / b.z`.) * The static version of this method creates a * new p5.Vector while the non-static version acts on the vector directly. * Additionally, you may provide arguments to this method as an array. @@ -958,10 +959,10 @@ p5.Vector.prototype.div = function div(x, y, z) { }; /** * Calculates the magnitude (length) of the vector and returns the result as - * a float (this is simply the equation sqrt(x\*x + y\*y + z\*z).) + * a float. (This is simply the equation `sqrt(x*x + y*y + z*z)`.) * * @method mag - * @return {Number} magnitude of the vector + * @return {Number} The magnitude of the vector * @example *
* @@ -1006,12 +1007,12 @@ p5.Vector.prototype.mag = function mag() { /** * Calculates the squared magnitude of the vector and returns the result - * as a float (this is simply the equation (x\*x + y\*y + z\*z).) + * as a float. (This is simply the equation `x*x + y*y + z*z`.) * Faster if the real length is not required in the * case of comparing vectors, etc. * * @method magSq - * @return {number} squared magnitude of the vector + * @return {number} The squared magnitude of the vector * @example *
* @@ -1064,10 +1065,10 @@ p5.Vector.prototype.magSq = function magSq() { * method. See the examples for more context. * * @method dot - * @param {Number} x x component of the vector - * @param {Number} [y] y component of the vector - * @param {Number} [z] z component of the vector - * @return {Number} the dot product + * @param {Number} x The x component of the vector + * @param {Number} [y] The y component of the vector + * @param {Number} [z] The z component of the vector + * @return {Number} The dot product * * @example *
@@ -1148,8 +1149,8 @@ p5.Vector.prototype.cross = function cross(v) { * If you are looking to calculate distance between 2 points see dist() * * @method dist - * @param {p5.Vector} v the x, y, and z coordinates of a p5.Vector - * @return {Number} the distance + * @param {p5.Vector} v The x, y, and z coordinates of a p5.Vector + * @return {Number} The distance * @example *
* @@ -1218,7 +1219,7 @@ p5.Vector.prototype.dist = function dist(v) { * Normalize the vector to length 1 (make it a unit vector). * * @method normalize - * @return {p5.Vector} normalized p5.Vector + * @return {p5.Vector} The normalized p5.Vector * @example *
* @@ -1285,11 +1286,11 @@ p5.Vector.prototype.normalize = function normalize() { }; /** - * Limit the magnitude of this vector to the value used for the max + * Limit the magnitude of this vector to the value used for the `max` * parameter. * * @method limit - * @param {Number} max the maximum magnitude for the vector + * @param {Number} max The maximum magnitude for the vector * @chainable * @example *
@@ -1343,11 +1344,11 @@ p5.Vector.prototype.limit = function limit(max) { }; /** - * Set the magnitude of this vector to the value used for the len + * Set the magnitude of this vector to the value used for the `len` * parameter. * * @method setMag - * @param {number} len the new length for this vector + * @param {number} len The new length for this vector * @chainable * @example *
@@ -1405,7 +1406,7 @@ p5.Vector.prototype.setMag = function setMag(n) { * consideration, and give the angle in radians or degree accordingly. * * @method heading - * @return {Number} the angle of rotation + * @return {Number} The angle of rotation * @example *
* @@ -1471,11 +1472,11 @@ p5.Vector.prototype.heading = function heading() { }; /** - * Rotate the vector to a specific angle (only 2D vectors), magnitude remains the + * Rotate the vector to a specific angle (only 2D vectors); magnitude remains the * same. * * @method setHeading - * @param {number} angle the angle of rotation + * @param {number} angle The angle of rotation * @chainable * @example *
@@ -1496,11 +1497,11 @@ p5.Vector.prototype.setHeading = function setHeading(a) { }; /** - * Rotate the vector by an angle (only 2D vectors), magnitude remains the + * Rotate the vector by an angle (only 2D vectors); magnitude remains the * same. * * @method rotate - * @param {number} angle the angle of rotation + * @param {number} angle The angle of rotation * @chainable * @example *
@@ -1570,8 +1571,8 @@ p5.Vector.prototype.rotate = function rotate(a) { * give the angle in radians or degree accordingly. * * @method angleBetween - * @param {p5.Vector} value the x, y, and z components of a p5.Vector - * @return {Number} the angle between (in radians) + * @param {p5.Vector} value The x, y, and z components of a p5.Vector + * @return {Number} The angle between (in radians) * @example *
* @@ -1648,10 +1649,10 @@ p5.Vector.prototype.angleBetween = function angleBetween(v) { * Linear interpolate the vector to another vector. * * @method lerp - * @param {Number} x the x component - * @param {Number} y the y component - * @param {Number} z the z component - * @param {Number} amt the amount of interpolation; some value between 0.0 + * @param {Number} x The x component + * @param {Number} y The y component + * @param {Number} z The z component + * @param {Number} amt The amount of interpolation; some value between 0.0 * (old vector) and 1.0 (new vector). 0.9 is very near * the new vector. 0.5 is halfway in between. * @chainable @@ -1719,7 +1720,7 @@ p5.Vector.prototype.angleBetween = function angleBetween(v) { */ /** * @method lerp - * @param {p5.Vector} v the p5.Vector to lerp to + * @param {p5.Vector} v The p5.Vector to lerp to * @param {Number} amt * @chainable */ @@ -1738,7 +1739,7 @@ p5.Vector.prototype.lerp = function lerp(x, y, z, amt) { * This method acts on the vector directly. * * @method reflect - * @param {p5.Vector} surfaceNormal the p5.Vector to reflect about, will be normalized by this method + * @param {p5.Vector} surfaceNormal The p5.Vector to reflect about; will be normalized by this method. * @chainable * @example *
@@ -1795,7 +1796,7 @@ p5.Vector.prototype.reflect = function reflect(surfaceNormal) { * array. * * @method array - * @return {Number[]} an Array with the 3 values + * @return {Number[]} An Array with the 3 values * @example *
* @@ -1824,10 +1825,10 @@ p5.Vector.prototype.array = function array() { * Equality check against a p5.Vector. * * @method equals - * @param {Number} [x] the x component of the vector - * @param {Number} [y] the y component of the vector - * @param {Number} [z] the z component of the vector - * @return {Boolean} whether the vectors are equals + * @param {Number} [x] The x component of the vector + * @param {Number} [y] The y component of the vector + * @param {Number} [z] The z component of the vector + * @return {Boolean} Whether the vectors are equal * @example *
* @@ -1852,7 +1853,7 @@ p5.Vector.prototype.array = function array() { */ /** * @method equals - * @param {p5.Vector|Array} value the vector to compare + * @param {p5.Vector|Array} value The vector to compare * @return {Boolean} */ p5.Vector.prototype.equals = function equals(x, y, z) { @@ -1880,9 +1881,9 @@ p5.Vector.prototype.equals = function equals(x, y, z) { * * @method fromAngle * @static - * @param {Number} angle the desired angle, in radians (unaffected by angleMode) - * @param {Number} [length] the length of the new vector (defaults to 1) - * @return {p5.Vector} the new p5.Vector object + * @param {Number} angle The desired angle, in radians (unaffected by angleMode) + * @param {Number} [length] The length of the new vector (defaults to 1) + * @return {p5.Vector} The new p5.Vector object * @example *
* @@ -1931,11 +1932,11 @@ p5.Vector.fromAngle = function fromAngle(angle, length) { * * @method fromAngles * @static - * @param {Number} theta the polar angle, in radians (zero is up) - * @param {Number} phi the azimuthal angle, in radians + * @param {Number} theta The polar angle, in radians (zero is up) + * @param {Number} phi The azimuthal angle, in radians * (zero is out of the screen) - * @param {Number} [length] the length of the new vector (defaults to 1) - * @return {p5.Vector} the new p5.Vector object + * @param {Number} [length] The length of the new vector (defaults to 1) + * @return {p5.Vector} A new p5.Vector object * @example *
* @@ -1980,7 +1981,7 @@ p5.Vector.fromAngles = function(theta, phi, length) { * * @method random2D * @static - * @return {p5.Vector} the new p5.Vector object + * @return {p5.Vector} A new p5.Vector object * @example *
* @@ -2033,7 +2034,7 @@ p5.Vector.random2D = function random2D() { * * @method random3D * @static - * @return {p5.Vector} the new p5.Vector object + * @return {p5.Vector} A new p5.Vector object * @example *
* @@ -2059,10 +2060,10 @@ p5.Vector.random3D = function random3D() { /** * @method add * @static - * @param {p5.Vector} v1 a p5.Vector to add - * @param {p5.Vector} v2 a p5.Vector to add - * @param {p5.Vector} [target] the vector to receive the result - * @return {p5.Vector} the resulting p5.Vector + * @param {p5.Vector} v1 A p5.Vector to add + * @param {p5.Vector} v2 A p5.Vector to add + * @param {p5.Vector} [target] The vector to receive the result + * @return {p5.Vector} The resulting p5.Vector */ p5.Vector.add = function add(v1, v2, target) { @@ -2085,15 +2086,15 @@ p5.Vector.add = function add(v1, v2, target) { /** * @method rem * @static - * @param {p5.Vector} v1 dividend p5.Vector - * @param {p5.Vector} v2 divisor p5.Vector + * @param {p5.Vector} v1 The dividend p5.Vector + * @param {p5.Vector} v2 The divisor p5.Vector */ /** * @method rem * @static * @param {p5.Vector} v1 * @param {p5.Vector} v2 - * @return {p5.Vector} the resulting p5.Vector + * @return {p5.Vector} The resulting p5.Vector */ p5.Vector.rem = function rem(v1, v2) { if (v1 instanceof p5.Vector && v2 instanceof p5.Vector) { @@ -2105,15 +2106,15 @@ p5.Vector.rem = function rem(v1, v2) { /* * Subtracts one p5.Vector from another and returns a new one. The second - * vector (v2) is subtracted from the first (v1), resulting in v1-v2. + * vector (`v2`) is subtracted from the first (`v1`), resulting in `v1-v2`. */ /** * @method sub * @static - * @param {p5.Vector} v1 a p5.Vector to subtract from - * @param {p5.Vector} v2 a p5.Vector to subtract - * @param {p5.Vector} [target] the vector to receive the result - * @return {p5.Vector} the resulting p5.Vector + * @param {p5.Vector} v1 A p5.Vector to subtract from + * @param {p5.Vector} v2 A p5.Vector to subtract + * @param {p5.Vector} [target] The vector to receive the result + * @return {p5.Vector} The resulting p5.Vector */ p5.Vector.sub = function sub(v1, v2, target) { @@ -2185,7 +2186,7 @@ p5.Vector.mult = function mult(v, n, target) { }; /** - * Rotates the vector (only 2D vectors) by the given angle, magnitude remains the same and returns a new vector. + * Rotates the vector (only 2D vectors) by the given angle; magnitude remains the same. Returns a new vector. */ /** @@ -2193,7 +2194,7 @@ p5.Vector.mult = function mult(v, n, target) { * @static * @param {p5.Vector} v * @param {Number} angle - * @param {p5.Vector} [target] the vector to receive the result + * @param {p5.Vector} [target] The vector to receive the result */ p5.Vector.rotate = function rotate(v, a, target) { if (arguments.length === 2) { @@ -2229,7 +2230,7 @@ p5.Vector.rotate = function rotate(v, a, target) { * @static * @param {p5.Vector} v * @param {Number} n - * @param {p5.Vector} [target] the vector to receive the result + * @param {p5.Vector} [target] The vector to receive the result */ /** @@ -2270,9 +2271,9 @@ p5.Vector.div = function div(v, n, target) { /** * @method dot * @static - * @param {p5.Vector} v1 the first p5.Vector - * @param {p5.Vector} v2 the second p5.Vector - * @return {Number} the dot product + * @param {p5.Vector} v1 The first p5.Vector + * @param {p5.Vector} v2 The second p5.Vector + * @return {Number} The dot product */ p5.Vector.dot = function dot(v1, v2) { return v1.dot(v2); @@ -2284,9 +2285,9 @@ p5.Vector.dot = function dot(v1, v2) { /** * @method cross * @static - * @param {p5.Vector} v1 the first p5.Vector - * @param {p5.Vector} v2 the second p5.Vector - * @return {Number} the cross product + * @param {p5.Vector} v1 The first p5.Vector + * @param {p5.Vector} v2 The second p5.Vector + * @return {Number} The cross product */ p5.Vector.cross = function cross(v1, v2) { return v1.cross(v2); @@ -2299,9 +2300,9 @@ p5.Vector.cross = function cross(v1, v2) { /** * @method dist * @static - * @param {p5.Vector} v1 the first p5.Vector - * @param {p5.Vector} v2 the second p5.Vector - * @return {Number} the distance + * @param {p5.Vector} v1 The first p5.Vector + * @param {p5.Vector} v2 The second p5.Vector + * @return {Number} The distance */ p5.Vector.dist = function dist(v1, v2) { return v1.dist(v2); @@ -2317,8 +2318,8 @@ p5.Vector.dist = function dist(v1, v2) { * @param {p5.Vector} v1 * @param {p5.Vector} v2 * @param {Number} amt - * @param {p5.Vector} [target] the vector to receive the result - * @return {p5.Vector} the lerped value + * @param {p5.Vector} [target] The vector to receive the result + * @return {p5.Vector} The lerped value */ p5.Vector.lerp = function lerp(v1, v2, amt, target) { if (!target) { @@ -2338,13 +2339,13 @@ p5.Vector.lerp = function lerp(v1, v2, amt, target) { /** * Calculates the magnitude (length) of the vector and returns the result as - * a float (this is simply the equation sqrt(x\*x + y\*y + z\*z).) + * a float (this is simply the equation `sqrt(x*x + y*y + z*z)`.) */ /** * @method mag * @static - * @param {p5.Vector} vecT the vector to return the magnitude of - * @return {Number} the magnitude of vecT + * @param {p5.Vector} vecT The vector to return the magnitude of + * @return {Number} The magnitude of vecT */ p5.Vector.mag = function mag(vecT) { const x = vecT.x, @@ -2360,9 +2361,9 @@ p5.Vector.mag = function mag(vecT) { /** * @method normalize * @static - * @param {p5.Vector} v the vector to normalize - * @param {p5.Vector} [target] the vector to receive the result - * @return {p5.Vector} v normalized to a length of 1 + * @param {p5.Vector} v The vector to normalize + * @param {p5.Vector} [target] The vector to receive the result + * @return {p5.Vector} The vector v, normalized to a length of 1 */ p5.Vector.normalize = function normalize(v, target) { if (arguments.length < 2) {