From 3cdb11fe36e878e60d9b2a4fecb25ef8687415af Mon Sep 17 00:00:00 2001
From: Jonathan Puckey <me@jonathanpuckey.com>
Date: Sun, 3 Mar 2013 19:47:32 +0100
Subject: [PATCH] GradientStop & PathItem example documentation.

---
 src/color/GradientStop.js | 19 +++++++++++-----
 src/path/PathItem.js      | 47 ++++++++++++++++++++++++++-------------
 2 files changed, 45 insertions(+), 21 deletions(-)

diff --git a/src/color/GradientStop.js b/src/color/GradientStop.js
index b99b665b..f878f406 100644
--- a/src/color/GradientStop.js
+++ b/src/color/GradientStop.js
@@ -22,7 +22,7 @@ var GradientStop = this.GradientStop = Base.extend(/** @lends GradientStop# */{
 	 *
 	 * @param {Color} [color=new RgbColor(0, 0, 0)] the color of the stop
 	 * @param {Number} [rampPoint=0] the position of the stop on the gradient
-	 *                               ramp {@default 0}
+	 *                               ramp as a value between 0 and 1.
 	 */
 	initialize: function(arg0, arg1) {
 		if (arg0) {
@@ -82,22 +82,26 @@ var GradientStop = this.GradientStop = Base.extend(/** @lends GradientStop# */{
 	 * // Create a circle shaped path at the center of the view,
 	 * // using 40% of the height of the view as its radius
 	 * // and fill it with a radial gradient color:
-	 * var path = new Path.Circle(view.center, view.bounds.height * 0.4);
-	 *
+	 * var path = new Path.Circle({
+	 * 	center: view.center,
+	 * 	radius: view.bounds.height * 0.4
+	 * });
+	 * 
 	 * // Prepare the gradient color and apply it to the path:
 	 * var colors = [['yellow', 0.05], ['red', 0.2], ['black', 1]];
 	 * var gradient = new RadialGradient(colors);
 	 * var from = path.position;
 	 * var to = path.bounds.rightCenter;
 	 * var gradientColor = new GradientColor(gradient, from, to);
+	 * 
 	 * path.fillColor = gradientColor;
-	 *
+	 * 
 	 * // This function is called each frame of the animation:
 	 * function onFrame(event) {
 	 * 	var blackStop = gradient.stops[2];
 	 * 	// Animate the rampPoint between 0.7 and 0.9:
 	 * 	blackStop.rampPoint = Math.sin(event.time * 5) * 0.1 + 0.8;
-	 *
+	 * 
 	 * 	// Animate the rampPoint between 0.2 and 0.4
 	 * 	var redStop = gradient.stops[1];
 	 * 	redStop.rampPoint = Math.sin(event.time * 3) * 0.1 + 0.3;
@@ -125,7 +129,10 @@ var GradientStop = this.GradientStop = Base.extend(/** @lends GradientStop# */{
 	 * // Create a circle shaped path at the center of the view,
 	 * // using 40% of the height of the view as its radius
 	 * // and fill it with a radial gradient color:
-	 * var path = new Path.Circle(view.center, view.bounds.height * 0.4);
+	 * var path = new Path.Circle({
+	 * 	center: view.center,
+	 * 	radius: view.bounds.height * 0.4
+	 * });
 	 *
 	 * // Create a radial gradient that mixes red and black evenly:
 	 * var gradient = new RadialGradient('red', 'black');
diff --git a/src/path/PathItem.js b/src/path/PathItem.js
index 002f1fea..660ba97f 100644
--- a/src/path/PathItem.js
+++ b/src/path/PathItem.js
@@ -22,13 +22,37 @@
 var PathItem = this.PathItem = Item.extend(/** @lends PathItem# */{
 
 	/**
-	 * Returns all interesections between two {@link PathItem} items as an array
+	 * Returns all intersections between two {@link PathItem} items as an array
 	 * of {@link CurveLocation} objects. {@link CompoundPath} items are also
 	 * supported.
 	 *
-	 * @param {PathItem} the other item to find the intersections to.
+	 * @param {PathItem} path the other item to find the intersections to.
 	 * @return {CurveLocation[]} the locations of all intersection between the
 	 * paths
+	 * @example {@paperscript}
+	 * // Create a rectangular path with its top-left point at
+	 * // {x: 30, y: 25} and a size of {width: 50, height: 50}:
+	 * var path = new Path.Rectangle(new Point(30, 25), new Size(50, 50));
+	 * path.strokeColor = 'black';
+	 * 
+	 * var secondPath = path.clone();
+	 * var intersectionGroup = new Group();
+	 * 
+	 * function onFrame(event) {
+	 * 	secondPath.rotate(3);
+	 * 	
+	 * 	var intersections = path.getIntersections(secondPath);
+	 * 	intersectionGroup.removeChildren();
+	 * 
+	 * 	for (var i = 0; i < intersections.length; i++) {
+	 * 		var intersectionPath = new Path.Circle({
+	 * 			center: intersections[i].point,
+	 * 			radius: 4,
+	 * 			fillColor: 'red'
+	 * 		});
+	 * 		intersectionGroup.addChild(intersectionPath);
+	 * 	}
+	 * }
 	 */
 	getIntersections: function(path) {
 		// First check the bounds of the two paths. If they don't intersect,
@@ -242,34 +266,27 @@ var PathItem = this.PathItem = Item.extend(/** @lends PathItem# */{
 	 * @param {Number} [parameter=0.5]
 	 *
 	 * @example {@paperscript height=300}
-	 * // Interactive example. Click and drag in the view below:
+	 * // Interactive example. Move your mouse around the view below:
 	 *
 	 * var myPath;
-	 * function onMouseDrag(event) {
+	 * function onMouseMove(event) {
 	 * 	// If we created a path before, remove it:
 	 * 	if (myPath) {
-	 * 	    myPath.remove();
+	 * 		myPath.remove();
 	 * 	}
-	 *
+	 * 
 	 * 	// Create a new path and add a segment point to it
 	 * 	// at {x: 150, y: 150):
 	 * 	myPath = new Path();
 	 * 	myPath.add(150, 150);
-	 *
+	 * 
 	 * 	// Draw a curve through the position of the mouse to 'toPoint'
 	 * 	var toPoint = new Point(350, 150);
 	 * 	myPath.curveTo(event.point, toPoint);
-	 *
+	 * 
 	 * 	// Select the path, so we can see its segments:
 	 * 	myPath.selected = true;
 	 * }
-     *
-	 * // When the mouse is released, deselect the path
-	 * // and set its stroke-color to black:
-	 * function onMouseUp(event) {
-	 * 	myPath.selected = false;
-	 * 	myPath.strokeColor = 'black';
-	 * }
 	 */
 
 	/**