From 5809052cf002d4d7a49c80bad39df2cecd9afb3a Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Mon, 6 Oct 2014 21:23:21 -0700 Subject: [PATCH 1/5] Adds p5.Vector documentation --- src/objects/p5.Vector.js | 64 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/src/objects/p5.Vector.js b/src/objects/p5.Vector.js index 0205af2a13..dfd2c031d8 100644 --- a/src/objects/p5.Vector.js +++ b/src/objects/p5.Vector.js @@ -43,8 +43,8 @@ define(function (require) { * ellipse(vector2.x, vector2.y, 50, 50); * vector.add(vector2); * ellipse(vector.x, vector.y, 50, 50); - * - * + * + * */ p5.Vector = function() { var x,y,z; @@ -91,6 +91,19 @@ define(function (require) { * p5.Vector or an Array * @param {Number} [y] the y component of the vector * @param {Number} [z] the z component of the vector + * @example + * + *
+ * function setup() { + * var v = createVector(1,2,3); + * v.set(4,5,6); //Sets vector to [4,5,6] + * + * var v1 = createVector(0,0,0); + * var arr = [1,2,3] + * v1.set(arr); //Sets vector to [1,2,3] + * } + *
+ * */ p5.Vector.prototype.set = function (x, y, z) { if (x instanceof p5.Vector) { @@ -142,6 +155,22 @@ define(function (require) { * @param {Number} [z] the z component of the vector to be * added * @return {p5.Vector} the p5.Vector object. + * @example + *
+ * + * var v = createVector(1,2,3); + * v.add(4,5,6); //v's compnents are set to [5,7,9] + * + *
+ *
+ * + * //Static method + * var v = createVector(1,2,3); + * var v1 = createVector(2,3,4); + * + * var v2 = p5.Vector.add(v, v1); //v2 has compnents [3,5,7] + * + *
*/ p5.Vector.prototype.add = function (x, y, z) { if (x instanceof p5.Vector) { @@ -176,6 +205,22 @@ define(function (require) { * @param {Number} [y] the y component of the vector * @param {Number} [z] the z component of the vector * @return {p5.Vector} p5.Vector object. + * @example + *
+ * + * var v = createVector(4,5,6); + * v.sub(1,1,1); //v's compnents are set to [3,4,5] + * + *
+ *
+ * + * //Static method + * var v = createVector(2,3,4); + * var v1 = createVector(1,2,3); + * + * var v2 = p5.Vector.sub(v, v1); //v2 has compnents [1,1,1] + * + *
*/ p5.Vector.prototype.sub = function (x, y, z) { if (x instanceof p5.Vector) { @@ -203,6 +248,21 @@ define(function (require) { * @chainable * @param {Number} n the number to multiply with the vector * @return {p5.Vector} a reference to the p5.Vector object (allow chaining) + * @example + *
+ * + * var v = createVector(1,2,3); + * v.mult(2); //v's compnents are set to [2,4,6] + * + *
+ *
+ * + * //Static method + * var v = createVector(1,2,3); + * + * var v1 = p5.Vector.mult(v, 2); //v1 has compnents [2,4,6] + * + *
*/ p5.Vector.prototype.mult = function (n) { this.x *= n || 0; From a76ed222370f329e3817bd5b8cfd5ec0a196edf8 Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Mon, 6 Oct 2014 22:27:15 -0700 Subject: [PATCH 2/5] Adds additional documentation for static/non-static p5.Vector methods --- src/objects/p5.Vector.js | 111 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 108 insertions(+), 3 deletions(-) diff --git a/src/objects/p5.Vector.js b/src/objects/p5.Vector.js index dfd2c031d8..ed1ef04872 100644 --- a/src/objects/p5.Vector.js +++ b/src/objects/p5.Vector.js @@ -92,8 +92,8 @@ define(function (require) { * @param {Number} [y] the y component of the vector * @param {Number} [z] the z component of the vector * @example - * *
+ * * function setup() { * var v = createVector(1,2,3); * v.set(4,5,6); //Sets vector to [4,5,6] @@ -102,8 +102,8 @@ define(function (require) { * var arr = [1,2,3] * v1.set(arr); //Sets vector to [1,2,3] * } - *
* + * */ p5.Vector.prototype.set = function (x, y, z) { if (x instanceof p5.Vector) { @@ -278,6 +278,21 @@ define(function (require) { * @chainable * @param {number} n the number to divide the vector by * @return {p5.Vector} a reference to the p5.Vector object (allow chaining) + * @example + *
+ * + * var v = createVector(6,4,2); + * v.div(2); //v's compnents are set to [3,2,1] + * + *
+ *
+ * + * //Static method + * var v = createVector(6,4,2); + * + * var v1 = p5.Vector.div(v, 2); //v1 has compnents [3,2,1] + * + *
*/ p5.Vector.prototype.div = function (n) { this.x /= n; @@ -319,6 +334,24 @@ define(function (require) { * @param {Number} [y] y component of the vector * @param {Number} [z] z component of the vector * @return {Number} the dot product + * @example + *
+ * + * var v = createVector(1,2,3); + * var v1 = createVector(2,3,4); + * + * v.dot(v1); //Returns 20 + * + *
+ *
+ * + * //Static method + * var v = createVector(1,2,3); + * var v1 = createVector(3,2,1); + * + * var dotProduct = p5.Vector.dot(v,v1); //dotProduct == 10 + * + *
*/ p5.Vector.prototype.dot = function (x, y, z) { if (x instanceof p5.Vector) { @@ -336,6 +369,24 @@ define(function (require) { * @method cross * @param {p5.Vector} v p5.Vector to be crossed * @return {p5.Vector} p5.Vector composed of cross product + * @example + *
+ * + * var v = createVector(1,2,3); + * var v1 = createVector(1,2,3); + * + * v.cross(v1); //v's components are [0,0,0] + * + *
+ *
+ * + * //Static method + * var v = createVector(1,0,0); + * var v1 = createVector(0,1,0); + * + * var crossProduct = p5.Vector.cross(v,v1); //crossProduct has components [0,0,1] + * + *
*/ p5.Vector.prototype.cross = function (v) { var x = this.y * v.z - this.z * v.y; @@ -355,6 +406,24 @@ define(function (require) { * @method dist * @param {p5.Vector} v the x, y, and z coordinates of a p5.Vector * @return {Number} the distance + * @example + *
+ * + * var v = createVector(1,0,0); + * var v1 = createVector(0,1,0); + * + * var distance = v.dist(v1); //distance == 1.4142... + * + *
+ *
+ * + * //Static method + * var v = createVector(1,0,0); + * var v1 = createVector(0,1,0); + * + * var distance = p5.Vector.dist(v,v1); //distance == 1.4142... + * + *
*/ p5.Vector.prototype.dist = function (v) { var d = v.get().sub(this); @@ -451,6 +520,23 @@ define(function (require) { * (old vector) and 1.0 (new vector). 0.1 is very near * the new vector. 0.5 is halfway in between. * @return {p5.Vector} the modified p5.Vector + * @example + *
+ * + * var v = createVector(1,1,0); + * + * v.lerp(3,3,0,0.5); //v now has components [2,2,0] + * + *
+ *
+ * + * var v = createVector(0,0,0); + * var v1 = createVector(100,100,0); + * + * var v2 = p5.Vector.lerp(v,v1,0.5); + * //v2 has components [50,50,0] + * + *
*/ p5.Vector.prototype.lerp = function (x, y, z, amt) { if (x instanceof p5.Vector) { @@ -486,6 +572,13 @@ define(function (require) { * @static * @param {Number} angle the desired angle * @return {p5.Vector} the new p5.Vector object + * @example + *
+ * + * var v = p5.Vector.fromAngle(PI / 2); + * //v has components [0,1,0] + * + *
*/ p5.Vector.fromAngle = function(angle) { if (this.p5) { @@ -506,6 +599,12 @@ define(function (require) { * @method random2D * @static * @return {p5.Vector} the new p5.Vector object + * @example + *
+ * + * var v = p5.Vector.random2D(); + * + *
*/ p5.Vector.random2D = function () { var angle; @@ -529,6 +628,12 @@ define(function (require) { * @method random3D * @static * @return {p5.Vector} the new p5.Vector object + * @example + *
+ * + * var v = p5.Vector.random3D(); + * + *
*/ p5.Vector.random3D = function () { var angle,vz; @@ -657,7 +762,7 @@ define(function (require) { /** * Calculates and returns the angle (in radians) between two vectors. - * + * @method angleBetween * @static * @param {p5.Vector} v1 the x, y, and z components of a p5.Vector * @param {p5.Vector} v2 the x, y, and z components of a p5.Vector From 617997b6b43f94c9bbf97cb582e9e27ed5eef4a3 Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Mon, 6 Oct 2014 22:40:44 -0700 Subject: [PATCH 3/5] Adds inline example for angleBetween --- src/objects/p5.Vector.js | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/objects/p5.Vector.js b/src/objects/p5.Vector.js index ed1ef04872..d8608b39a4 100644 --- a/src/objects/p5.Vector.js +++ b/src/objects/p5.Vector.js @@ -767,7 +767,16 @@ define(function (require) { * @param {p5.Vector} v1 the x, y, and z components of a p5.Vector * @param {p5.Vector} v2 the x, y, and z components of a p5.Vector * @return {Number} the angle between - * + * @example + *
+ * + * var v = createVector(1,0,0); + * var v1 = createVector(0,1,0); + * + * var angle = p5.Vector.angleBetween(v,v1); + * //angle == (PI / 2) + * + *
*/ p5.Vector.angleBetween = function (v1, v2) { var angle = Math.acos(v1.dot(v2) / (v1.mag() * v2.mag())); From 2fd45e120e68a6158bcc549fcfb6f71066aa4000 Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Mon, 6 Oct 2014 23:20:35 -0700 Subject: [PATCH 4/5] Adds additional documentation to non-static/static methods --- src/objects/p5.Vector.js | 48 ++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/src/objects/p5.Vector.js b/src/objects/p5.Vector.js index d8608b39a4..a9906cf412 100644 --- a/src/objects/p5.Vector.js +++ b/src/objects/p5.Vector.js @@ -35,10 +35,10 @@ define(function (require) { * @param {Number} [z] z component of the vector * @example *
- * + * * var vector = createVector(40, 50); * var vector2 = createVector(40, 50); - * + * * ellipse(vector.x, vector.y, 50, 50); * ellipse(vector2.x, vector2.y, 50, 50); * vector.add(vector2); @@ -86,11 +86,11 @@ define(function (require) { * Sets the x, y, and z component 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|p5.Vector|Array} [x] the x component of the vector or a * p5.Vector or an Array - * @param {Number} [y] the y component of the vector - * @param {Number} [z] the z component of the vector + * @param {Number} [y] the y component of the vector + * @param {Number} [z] the z component of the vector * @example *
* @@ -144,8 +144,8 @@ define(function (require) { * 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 * have no return value -- they act directly on the vector. See the examples - * for more context. - * + * for more context. + * * @method add * @chainable * @param {Number|p5.Vector|Array} x the x component of the vector to be @@ -196,8 +196,8 @@ define(function (require) { * another, or subtracts two independent vectors. The version of the method * that substracts two vectors is a static method and returns a p5.Vector, the * others have no return value -- they act directly on the vector. See the - * examples for more context. - * + * examples for more context. + * * @method sub * @chainable * @param {Number|p5.Vector|Array} x the x component of the vector or a @@ -242,7 +242,7 @@ define(function (require) { }; /** - * Multiply the vector by a scalar. + * Multiply the vector by a scalar. * * @method mult * @chainable @@ -272,7 +272,7 @@ define(function (require) { }; /** - * Divide the vector by a scalar. + * Divide the vector by a scalar. * * @method div * @chainable @@ -304,7 +304,7 @@ define(function (require) { /** * 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).) - * + * * @method mag * @return {Number} magnitude of the vector */ @@ -327,7 +327,10 @@ define(function (require) { }; /** - * Calculates the dot product of two vectors. + * Calculates the dot product of two vectors. The version of the method + * that computes the dot product of two independent vectors is a static method. + * See the examples for more context. + * * * @method dot * @param {Number|p5.Vector} x x component of the vector or a p5.Vector @@ -364,7 +367,8 @@ define(function (require) { /** * Calculates and returns a vector composed of the cross product between - * two vectors. + * two vectors. The version of the method that computes the cross product of two independent vectors is a static method. + * See the examples for more context. * * @method cross * @param {p5.Vector} v p5.Vector to be crossed @@ -514,7 +518,7 @@ define(function (require) { * * @method lerp * @param {p5.Vector} x the x component or the p5.Vector to lerp to - * @param {p5.Vector} [y] y the y component + * @param {p5.Vector} [y] y the y component * @param {p5.Vector} [z] z the z component * @param {Number} amt the amount of interpolation; some value between 0.0 * (old vector) and 1.0 (new vector). 0.1 is very near @@ -532,7 +536,7 @@ define(function (require) { * * var v = createVector(0,0,0); * var v1 = createVector(100,100,0); - * + * * var v2 = p5.Vector.lerp(v,v1,0.5); * //v2 has components [50,50,0] * @@ -555,7 +559,7 @@ define(function (require) { * array. * * @method array - * @return {Array} an Array with the 3 values + * @return {Array} an Array with the 3 values */ p5.Vector.prototype.array = function () { return [this.x || 0, this.y || 0, this.z || 0]; @@ -563,11 +567,11 @@ define(function (require) { // Static Methods - + /** * Make a new 2D unit vector from an angle - * + * * @method fromAngle * @static * @param {Number} angle the desired angle @@ -608,7 +612,7 @@ define(function (require) { */ p5.Vector.random2D = function () { var angle; - // A lot of nonsense to determine if we know about a + // A lot of nonsense to determine if we know about a // p5 sketch and whether we should make a random angle in degrees or radians if (this.p5) { if (this.p5._angleMode === constants.DEGREES) { @@ -766,8 +770,8 @@ define(function (require) { * @static * @param {p5.Vector} v1 the x, y, and z components of a p5.Vector * @param {p5.Vector} v2 the x, y, and z components of a p5.Vector - * @return {Number} the angle between - * @example + * @return {Number} the angle between (in radians) + * @example *
* * var v = createVector(1,0,0); From 8b44e0bb7a617b4c3b7c0cddddf9def12776da76 Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Wed, 8 Oct 2014 20:44:17 -0700 Subject: [PATCH 5/5] Refines description of p5.Vector static/non static methods --- src/objects/p5.Vector.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/objects/p5.Vector.js b/src/objects/p5.Vector.js index a9906cf412..ab85b618fe 100644 --- a/src/objects/p5.Vector.js +++ b/src/objects/p5.Vector.js @@ -143,8 +143,7 @@ define(function (require) { * 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 - * have no return value -- they act directly on the vector. See the examples - * for more context. + * acts directly on the vector. See the examples for more context. * * @method add * @chainable @@ -194,9 +193,8 @@ define(function (require) { /** * 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 substracts two vectors is a static method and returns a p5.Vector, the - * others have no return value -- they act directly on the vector. See the - * examples for more context. + * that subtracts two vectors is a static method and returns a p5.Vector, the + * other acts directly on the vector. See the examples for more context. * * @method sub * @chainable @@ -242,7 +240,8 @@ define(function (require) { }; /** - * Multiply the vector by a scalar. + * Multiply the vector by a scalar. The static version of this method creates a new p5.Vector + * while the non static version acts on the vector directly. See the examples for more context. * * @method mult * @chainable @@ -272,7 +271,8 @@ define(function (require) { }; /** - * Divide the vector by a scalar. + * Divide the vector by a scalar. The static version of this method creates a new p5.Vector + * while the non static version acts on the vector directly. See the examples for more context. * * @method div * @chainable @@ -367,7 +367,7 @@ define(function (require) { /** * Calculates and returns a vector composed of the cross product between - * two vectors. The version of the method that computes the cross product of two independent vectors is a static method. + * two vectors. Both the static and non static methods return a new p5.Vector. * See the examples for more context. * * @method cross