Merge remote-tracking branch 'origin/master'

src/path/Path.js

@@ -333,6 +333,24 @@ var Path = this.Path = PathItem.extend({
 	 * // Add two segments in one go at {x: 100, y: 20}
 	 * // and {x: 170, y: 75}:
 	 * path.add({x: 100, y: 20}, {x: 170, y: 75});
+	 * 
+	 * @example {@paperscript}
+	 * // Adding a segment with handles to a path:
+	 * var path = new Path();
+	 * path.strokeColor = 'black';
+	 * 
+	 * path.add(new Point(30, 75));
+	 * 
+	 * // Add a segment with handles:
+	 * var point = new Point(100, 20);
+	 * var handleIn = new Point(-50, 0);
+	 * var handleOut = new Point(50, 0);
+	 * var added = path.add(new Segment(point, handleIn, handleOut));
+	 * 
+	 * // Select the added segment, so we can see its handles:
+	 * added.selected = true;
+	 * 
+	 * path.add(new Point(170, 75));
 	 */
 	add: function(segment1 /*, segment2, ... */) {
 		return arguments.length > 1 && typeof segment1 !== 'number'
@@ -1301,6 +1319,49 @@ var Path = this.Path = PathItem.extend({
 		 * open ended and closed paths.
 		 * 
 		 * @author Oleg V. Polikarpotchkin
+		 * 
+		 * @example {@paperscript}
+		 * // Smoothing a closed shape:
+		 * 
+		 * // 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';
+		 * 
+		 * // Select the path, so we can see its handles:
+		 * path.selected = true;
+		 * 
+		 * // Create a copy of the path and move it 100pt to the right:
+		 * var copy = path.clone();
+		 * copy.position.x += 100;
+		 * 
+		 * // Smooth the segments of the copy:
+		 * copy.smooth();
+		 * 
+		 * @example {@paperscript height=220}
+		 * var path = new Path();
+		 * path.strokeColor = 'black';
+		 * 
+		 * path.add(new Point(30, 50));
+		 * 
+		 * var y = 5;
+		 * var x = 3;
+		 * 
+		 * for (var i = 0; i < 28; i++) {
+		 *     y *= -1.1;
+		 *     x *= 1.1;
+		 *     path.lineBy(x, y);
+		 * }
+		 * 
+		 * // Create a copy of the path and move it 100pt down:
+		 * var copy = path.clone();
+		 * copy.position.y += 120;
+		 * 
+		 * // Set its stroke color to red:
+		 * copy.strokeColor = 'red';
+		 * 
+		 * // Smooth the segments of the copy:
+		 * copy.smooth();
 		 */
 		smooth: function() {
 			// This code is based on the work by Oleg V. Polikarpotchkin,

src/path/Segment.js

@@ -31,18 +31,17 @@ var Segment = this.Segment = Base.extend({
 	 *        anchor point of the segment that describes the out tangent of the
 	 *        segment.
 	 * 
-	 * @example
-	 * var handleIn = new Point(-40, -50);
-	 * var handleOut = new Point(40, 50);
-	 *
+	 * @example {@paperscript}
+	 * var handleIn = new Point(-80, -100);
+	 * var handleOut = new Point(80, 100);
+	 * 
 	 * var firstPoint = new Point(100, 50);
 	 * var firstSegment = new Segment(firstPoint, null, handleOut);
-	 *
-	 * var secondPoint = new Point(200, 50);
+	 * 
+	 * var secondPoint = new Point(300, 50);
 	 * var secondSegment = new Segment(secondPoint, handleIn, null);
-	 *
-	 * var path = new Path();
-	 * path.segments = [firstSegment, secondSegment];
+	 * 
+	 * var path = new Path(firstSegment, secondSegment);
 	 * path.strokeColor = 'black';
 	 * 
 	 * @class The Segment object represents a part of a path which is