Merge branch 'master' of github.com:lmccart/p5.js

Author: lauren mccarthy

src/math/noise.js

@@ -81,14 +81,13 @@ define(function (require) {
    *
    * @method noise
    * @param  {Number} x   x-coordinate in noise space
-   * @param  {Number} [y] y-coordinate in noise space
-   * @param  {Number} [z] z-coordinate in noise space
+   * @param  {Number} y   y-coordinate in noise space
+   * @param  {Number} z   z-coordinate in noise space
    * @return {Number}     Perlin noise value (between 0 and 1) at specified
    *                      coordinates
    * @example
    * <div>
-   * <code>
-   * var xoff = 0.0;
+   * <code>var xoff = 0.0;
    * 
    * function draw() {
    *   background(204);
@@ -99,8 +98,7 @@ define(function (require) {
    * </code>
    * </div>
    * <div>
-   * <code>
-   * var noiseScale=0.02;
+   * <code>var noiseScale=0.02;
    * 
    * function draw() {
    *   background(0);
@@ -215,19 +213,66 @@ define(function (require) {
    * @method noiseDetail
    * @param {Number} lod number of octaves to be used by the noise
    * @param {Number} falloff falloff factor for each octave
+   * @example
+   * <div>
+   * <code>
+   * 
+   * var noiseVal;
+   * var noiseScale=0.02;
+   * 
+   * function setup() {
+   *   createCanvas(100,100);
+   * }
+   * 
+   * function draw() {
+   *   background(0);
+   *   for (var y = 0; y < height; y++) {
+   *     for (var x = 0; x < width/2; x++) {
+   *       noiseDetail(2,0.2);
+   *       noiseVal = noise((mouseX+x) * noiseScale, 
+   *                        (mouseY+y) * noiseScale);
+   *       stroke(noiseVal*255);
+   *       point(x,y);
+   *       noiseDetail(8,0.65);
+   *       noiseVal = noise((mouseX + x + width/2) * noiseScale, 
+   *                        (mouseY + y) * noiseScale);
+   *       stroke(noiseVal*255);
+   *       point(x + width/2, y);
+   *     }
+   *   }
+   * }
+   * </code>
+   * </div>
    */
   p5.prototype.noiseDetail = function(lod, falloff) {
     if (lod>0)     { perlin_octaves=lod; }
     if (falloff>0) { perlin_amp_falloff=falloff; }
   };
 
   /**
-   * TODO: NOT IMPLEMENTED YET!
    * Sets the seed value for <b>noise()</b>. By default, <b>noise()</b>
    * produces different results each time the program is run. Set the
    * <b>value</b> parameter to a constant to return the same pseudo-random
    * numbers each time the software is run.
    *
+   * @method noiseSeed
+   * @param {Number} seed   the seed value
+   * @example
+   * <div>
+   * <code>var xoff = 0.0;
+   * 
+   * function setup() {
+   *   noiseSeed(99);
+   *   stroke(0, 10);
+   * }
+   * 
+   * function draw() {
+   *   xoff = xoff + .01;
+   *   var n = noise(xoff) * width;
+   *   line(n, 0, n, height);
+   * }
+   * </code>
+   * </div>
    */
   p5.prototype.noiseSeed = function(seed) {
     // Linear Congruential Generator

src/math/random.js

@@ -41,6 +41,27 @@ define(function (require) {
     };
   }());
 
+  /**
+   * Sets the seed value for random(). 
+   * 
+   * By default, random() produces different results each time the program 
+   * is run. Set the seed parameter to a constant to return the same 
+   * pseudo-random numbers each time the software is run.
+   *
+   * @method randomSeed
+   * @param {Number} seed   the seed value
+   * @example
+   * <div>
+   * <code>
+   * randomSeed(99);
+   * for (var i=0; i < 100; i++) {
+   *   var r = random(0, 255);
+   *   stroke(r);
+   *   line(i, 0, i, 100);
+   * }
+   * </code>
+   * </div>
+   */
   p5.prototype.randomSeed = function(seed) {
     lcg.setSeed(seed);
     seeded = true;
@@ -56,9 +77,35 @@ define(function (require) {
    * inclusive.
    *
    * @method random
-   * @param  {x}      min the lower bound
-   * @param  {y}      max the upper bound
-   * @return {Number}     the random number
+   * @param  {Number} min   the lower bound
+   * @param  {Number} max   the upper bound
+   * @return {Number} the random number
+   * @example
+   * <div>
+   * <code>
+   * for (var i = 0; i < 100; i++) {
+   *   var r = random(50);
+   *   stroke(r*5);
+   *   line(50, i, 50+r, i);
+   * }
+   * </code>
+   * </div>
+   * <div>
+   * <code>
+   * for (var i = 0; i < 100; i++) {
+   *   var r = random(-50, 50);
+   *   line(50,i,50+r,i);
+   * }
+   * </code>
+   * </div>
+   * <div>
+   * <code>
+   * // Get a random element from an array
+   * var words = [ "apple", "bear", "cat", "dog" ];
+   * var index = floor(random(words.length));  // Convert to integer
+   * text(words[index],10,50);  // Displays one of the four words
+   * </code>
+   * </div>
    */
   p5.prototype.random = function (min, max) {
 
@@ -101,10 +148,43 @@ define(function (require) {
    * If two args, first is mean, second is standard deviation
    *
    * @method randomGaussian
-   * @param  {mean}       mean
-   * @param  {sd}         standard deviation
-   * @return {Number}     the random number
-   */
+   * @param  {Number} mean  the mean
+   * @param  {Number} sd    the standard deviation
+   * @return {Number} the random number
+   * @example
+   * <div>
+   * <code>for (var y = 0; y < 100; y++) {
+   *  var x = randomGaussian(50,15);
+   *  line(50, y, x, y);
+   *}
+   * </code>
+   * </div>
+   * <div>
+   * <code> 
+   *var distribution = new Array(360);
+   * 
+   *function setup() {
+   *  createCanvas(100, 100);
+   *  for (var i = 0; i < distribution.length; i++) {
+   *    distribution[i] = floor(randomGaussian(0,15));
+   *  }
+   *}
+   * 
+   *function draw() {
+   *  background(204);
+   *   
+   *  translate(width/2, width/2);
+   * 
+   *  for (var i = 0; i < distribution.length; i++) {
+   *    rotate(TWO_PI/distribution.length);
+   *    stroke(0);
+   *    var dist = abs(distribution[i]);
+   *    line(0, 0, dist, 0);
+   *  }
+   *}
+   * </code>
+   * </div>
+   */ 
   var y2;
   var previous = false;
   p5.prototype.randomGaussian = function(mean, sd)  {

src/shape/2d_primitives.js

@@ -170,17 +170,30 @@ define(function (require) {
    * the stroke() function. A line cannot be filled, therefore the fill()
    * function will not affect the color of a line. 2D lines are drawn with a
    * width of one pixel by default, but this can be changed with the
-   * strokeWeight() function. The version with six parameters allows the line
-   * to be placed anywhere within XYZ space. Drawing this shape in 3D with the
-   * z parameter requires the P3D parameter in combination with size() as shown
-   * in the above example. 
+   * strokeWeight() function.
    * 
    * @method line
    * @param  {Number} x1 the x-coordinate of the first point
    * @param  {Number} y1 the y-coordinate of the first point
    * @param  {Number} x2 the x-coordinate of the second point
    * @param  {Number} y2 the y-coordinate of the second point
    * @return {p5}        the p5 object
+   * @example
+   * <div>
+   * <code>
+   * line(30, 20, 85, 75);
+   * </code>
+   * </div>
+   *
+   * <div>
+   * <code>
+   * line(30, 20, 85, 20);
+   * stroke(126);
+   * line(85, 20, 85, 75);
+   * stroke(255);
+   * line(85, 75, 30, 75);
+   * </code>
+   * </div>
    */
   p5.prototype.line = function(x1, y1, x2, y2) {
     var ctx = this.canvas.getContext('2d');
@@ -198,15 +211,21 @@ define(function (require) {
   /**
    * Draws a point, a coordinate in space at the dimension of one pixel.
    * The first parameter is the horizontal value for the point, the second
-   * value is the vertical value for the point, and the optional third value is
-   * the depth value. Drawing this shape in 3D with the z parameter requires
-   * the P3D parameter in combination with size() as shown in the above
-   * example.
+   * value is the vertical value for the point.
    * 
    * @method point
    * @param  {Number} x the x-coordinate
    * @param  {Number} y the y-coordinate
    * @return {p5}       the p5 object
+   * @example
+   * <div>
+   * <code>
+   * point(30, 20);
+   * point(85, 20);
+   * point(85, 75);
+   * point(30, 75);
+   * </code>
+   * </div>
    */
   p5.prototype.point = function(x, y) {
     var ctx = this.canvas.getContext('2d');
@@ -255,6 +274,12 @@ define(function (require) {
    * @param {type} x4 the x-coordinate of the fourth point
    * @param {type} y4 the y-coordinate of the fourth point
    * @return {p5}     the p5 object
+   * @example
+   * <div>
+   * <code>   
+   * quad(38, 31, 86, 20, 69, 63, 30, 76);
+   * </code>
+   * </div>
    */
   p5.prototype.quad = function(x1, y1, x2, y2, x3, y3, x4, y4) {
     var ctx = this.canvas.getContext('2d');
@@ -283,7 +308,12 @@ define(function (require) {
   * @param  {Number} c width of the rectangle
   * @param  {Number} d height of the rectangle
   * @return {p5}       the p5 object
-  * 
+  * @example
+  * <div>
+  * <code>
+  * rect(30, 20, 55, 55);
+  * </code>
+  * </div>
   */
   p5.prototype.rect = function(a, b, c, d) {
     var vals = canvas.modeAdjust(a, b, c, d, this._rectMode);
@@ -309,6 +339,12 @@ define(function (require) {
   * @param  {Number} x3 x-coordinate of the third point
   * @param  {Number} y3 y-coordinate of the third point
   * @return {p5}        the p5 object
+  * @example
+  * <div>
+  * <code>
+  * triangle(30, 75, 58, 20, 86, 75);
+  * </code>
+  * </div>
   */
   p5.prototype.triangle = function(x1, y1, x2, y2, x3, y3) {
     var ctx = this.canvas.getContext('2d');