Documentation: rearrange @example tags, improve examples, rename boolean -> Boolean and misc smaller edits.

src/basic/Line.js

@@ -23,7 +23,7 @@ var Line = this.Line = Base.extend({
 	 * 
 	 * @param {Point} point1
 	 * @param {Point} point2
-	 * @param {boolean} [infinite=true]
+	 * @param {Boolean} [infinite=true]
 	 * 
 	 * @class The Line object represents..
 	 * @constructs Line
@@ -65,7 +65,7 @@ var Line = this.Line = Base.extend({
 	 * Specifies whether the line extends infinitely
 	 *
 	 * @name Line#infinite
-	 * @type boolean
+	 * @type Boolean
 	 */
 
 	/**

src/basic/Matrix.js

@@ -381,7 +381,7 @@ var Matrix = this.Matrix = Base.extend({
 	},
 
 	/**
-	 * @return {boolean} Whether this transform is the identity transform.
+	 * @return {Boolean} Whether this transform is the identity transform.
 	 */
 	isIdentity: function() {
 		return this._m00 == 1 && this._m10 == 0 && this._m01 == 0 &&
@@ -392,7 +392,7 @@ var Matrix = this.Matrix = Base.extend({
 	 * Returns whether the transform is invertible. A transform is not
 	 * invertible if the determinant is 0 or any value is non-finite or NaN.
 	 *
-	 * @return {boolean} Whether the transform is invertible.
+	 * @return {Boolean} Whether the transform is invertible.
 	 */
 	isInvertible: function() {
 		var det = this.getDeterminant();
@@ -404,7 +404,7 @@ var Matrix = this.Matrix = Base.extend({
 	 * Checks whether the matrix is singular or not. Singular matrices cannot be
 	 * inverted.
 	 * 
-	 * @return {boolean} Whether the matrix is singular.
+	 * @return {Boolean} Whether the matrix is singular.
 	 */
 	isSingular: function() {
 		return !this.isInvertible();

src/basic/Point.js

@@ -27,6 +27,12 @@ var Point = this.Point = Base.extend({
 	 * @param {Number} x the x coordinate
 	 * @param {Number} y the y coordinate
 	 * 
+	 * @example
+	 * // Create a point at x: 10, y: 5
+	 * var point = new Point(10, 5);
+	 * console.log(point.x); // 10
+	 * console.log(point.y); // 5
+	 * 
 	 * @class The Point object represents a point in the two dimensional space
 	 * of the Paper.js project. It is also used to represent two dimensional
 	 * vector objects.
@@ -39,21 +45,87 @@ var Point = this.Point = Base.extend({
 	 * console.log(point.y); // 5
 	 * </pre>
 	 */
+	/**
+	 * Creates a Point object using the numbers in the given array as
+	 * coordinates.
+	 *
+	 * @name Point#initialize
+	 * @param {array} array
+	 * 
+	 * @example
+	 * // Creating a point at x: 10, y: 5 using an array of numbers:
+	 * var array = [10, 5];
+	 * var point = new Point(array);
+	 * console.log(point.x); // 10
+	 * console.log(point.y); // 5
+	 *
+	 * @example
+	 * // Passing an array to a functionality that expects a point:
+	 * 
+	 * // Create a circle shaped path at x: 50, y: 50
+	 * // with a radius of 30:
+	 * var path = new Path.Circle([50, 50], 30);
+	 * path.fillColor = 'red';
+	 * 
+	 * // Which is the same as doing:
+	 * var path = new Path.Circle(new Point(50, 50), 30);
+	 * path.fillColor = 'red';
+	 */
+	/**
+	 * Creates a Point object using the properties in the given object.
+	 *
+	 * @name Point#initialize
+	 * @param {object} object
+	 * 
+	 * @example
+	 * // Creating a point using an object literal with length and angle
+	 * // properties:
+	 * 
+	 * var point = new Point({
+	 * 	length: 10,
+	 * 	angle: 90
+	 * });
+	 * console.log(point.length); // 10
+	 * console.log(point.angle); // 90
+	 * 
+	 * @example
+	 * // Creating a point at x: 10, y: 20 using an object literal:
+	 * 
+	 * var point = new Point({
+	 * 	x: 10,
+	 * 	y: 20
+	 * });
+	 * console.log(point.x); // 10
+	 * console.log(point.y); // 20
+	 * 
+	 * @example
+	 * // Passing an object to a functionality that expects a point:
+	 * 
+	 * var center = {
+	 * 	x: 50,
+	 * 	y: 50
+	 * };
+	 * 
+	 * // Creates a circle shaped path at x: 50, y: 50
+	 * // with a radius of 30:
+	 * var path = new Path.Circle(center, 30);
+	 * path.fillColor = 'red';
+	 */
 	/**
 	 * Creates a Point object using the width and height values of the given
 	 * Size object.
 	 * 
-	 * Sample code:
+	 * @name Point#initialize
-	 * <code>
+	 * @param {Size} size
+	 * 
+	 * @example
+	 * // Creating a point using a size object.
+	 * 
 	 * // Create a Size with a width of 100pt and a height of 50pt
 	 * var size = new Size(100, 50);
 	 * console.log(size); // { width: 100, height: 50 }
 	 * var point = new Point(size);
 	 * console.log(point); // { x: 100, y: 50 }
-	 * </code>
-	 * 
-	 * @name Point#initialize
-	 * @param {Size} size
 	 */
 	/**
 	 * Creates a Point object using the coordinates of the given Point object.
@@ -113,7 +185,7 @@ var Point = this.Point = Base.extend({
 
 	/**
 	 * Returns a copy of the point.
-	 * This is useful as the following code only generates a flat copy:
+	 * 
 	 * @example
 	 * var point1 = new Point();
 	 * var point2 = point1;
@@ -141,31 +213,31 @@ var Point = this.Point = Base.extend({
 	 * the point as a new point.
 	 * The object itself is not modified!
 	 * 
-	 * @example
-	 * var point = new Point(5, 10);
-	 * var result = point + 20;
-	 * console.log(result); // { x: 25.0, y: 30.0 }
-	 * 
 	 * @name Point#add
 	 * @function
 	 * @param {Number} number the number to add
 	 * @return {Point} the addition of the point and the value as a new point
+	 * 
+	 * @example
+	 * var point = new Point(5, 10);
+	 * var result = point + 20;
+	 * console.log(result); // { x: 25.0, y: 30.0 }
 	 */
 	/**
 	 * Returns the addition of the supplied point to the point as a new
 	 * point.
 	 * The object itself is not modified!
 	 * 
+	 * @name Point#add
+	 * @function
+	 * @param {Point} point the point to add
+	 * @return {Point} the addition of the two points as a new point
+	 * 
 	 * @example
 	 * var point1 = new Point(5, 10);
 	 * var point2 = new Point(10, 20);
 	 * var result = point1 + point2;
 	 * console.log(result); // { x: 15.0, y: 30.0 }
-	 * 
-	 * @name Point#add
-	 * @function
-	 * @param {Point} point the point to add
-	 * @return {Point} the addition of the two points as a new point
 	 */
 	add: function(point) {
 		point = Point.read(arguments);
@@ -177,31 +249,31 @@ var Point = this.Point = Base.extend({
 	 * the point as a new point.
 	 * The object itself is not modified!
 	 * 
-	 * @example
-	 * var point = new Point(10, 20);
-	 * var result = point - 5;
-	 * console.log(result); // { x: 5.0, y: 15.0 }
-	 * 
 	 * @name Point#subtract
 	 * @function
 	 * @param {Number} number the number to subtract
 	 * @return {Point} the subtraction of the point and the value as a new point
+	 * 
+	 * @example
+	 * var point = new Point(10, 20);
+	 * var result = point - 5;
+	 * console.log(result); // { x: 5.0, y: 15.0 }
 	 */
 	/**
 	 * Returns the subtraction of the supplied point to the point as a new
 	 * point.
 	 * The object itself is not modified!
 	 * 
+	 * @name Point#subtract
+	 * @function
+	 * @param {Point} point the point to subtract
+	 * @return {Point} the subtraction of the two points as a new point
+	 * 
 	 * @example
 	 * var firstPoint = new Point(10, 20);
 	 * var secondPoint = new Point(5, 5);
 	 * var result = firstPoint - secondPoint;
 	 * console.log(result); // { x: 5.0, y: 15.0 }
-	 * 
-	 * @name Point#subtract
-	 * @function
-	 * @param {Point} point the point to subtract
-	 * @return {Point} the subtraction of the two points as a new point
 	 */
 	subtract: function(point) {
 		point = Point.read(arguments);
@@ -213,31 +285,31 @@ var Point = this.Point = Base.extend({
 	 * the point as a new point.
 	 * The object itself is not modified!
 	 * 
-	 * @example
-	 * var point = new Point(10, 20);
-	 * var result = point * 2;
-	 * console.log(result); // { x: 20.0, y: 40.0 }
-	 * 
 	 * @name Point#multiply
 	 * @function
 	 * @param {Number} number the number to multiply by
 	 * @return {Point} the multiplication of the point and the value as a new point
+	 * 
+	 * @example
+	 * var point = new Point(10, 20);
+	 * var result = point * 2;
+	 * console.log(result); // { x: 20.0, y: 40.0 }
 	 */
 	/**
 	 * Returns the multiplication of the supplied point to the point as a new
 	 * point.
 	 * The object itself is not modified!
 	 * 
+	 * @name Point#multiply
+	 * @function
+	 * @param {Point} point the point to multiply by
+	 * @return {Point} the multiplication of the two points as a new point
+	 * 
 	 * @example
 	 * var firstPoint = new Point(5, 10);
 	 * var secondPoint = new Point(4, 2);
 	 * var result = firstPoint * secondPoint;
 	 * console.log(result); // { x: 20.0, y: 20.0 }
-	 * 
-	 * @name Point#multiply
-	 * @function
-	 * @param {Point} point the point to multiply by
-	 * @return {Point} the multiplication of the two points as a new point
 	 */
 	multiply: function(point) {
 		point = Point.read(arguments);
@@ -249,31 +321,31 @@ var Point = this.Point = Base.extend({
 	 * the point as a new point.
 	 * The object itself is not modified!
 	 * 
-	 * @example
-	 * var point = new Point(10, 20);
-	 * var result = point / 2;
-	 * console.log(result); // { x: 5.0, y: 10.0 }
-	 * 
 	 * @name Point#divide
 	 * @function
 	 * @param {Number} number the number to divide by
 	 * @return {Point} the division of the point and the value as a new point
+	 * 
+	 * @example
+	 * var point = new Point(10, 20);
+	 * var result = point / 2;
+	 * console.log(result); // { x: 5.0, y: 10.0 }
 	 */
 	/**
 	 * Returns the division of the supplied point to the point as a new
 	 * point.
 	 * The object itself is not modified!
 	 * 
+	 * @name Point#divide
+	 * @function
+	 * @param {Point} point the point to divide by
+	 * @return {Point} the division of the two points as a new point
+	 * 
 	 * @example
 	 * var firstPoint = new Point(8, 10);
 	 * var secondPoint = new Point(2, 5);
 	 * var result = firstPoint / secondPoint;
 	 * console.log(result); // { x: 4.0, y: 2.0 }
-	 * 
-	 * @name Point#divide
-	 * @function
-	 * @param {Point} point the point to divide by
-	 * @return {Point} the division of the two points as a new point
 	 */
 	divide: function(point) {
 		point = Point.read(arguments);
@@ -284,29 +356,29 @@ var Point = this.Point = Base.extend({
 	 * The modulo operator returns the integer remainders of dividing the point
 	 * by the supplied value as a new point.
 	 * 
-	 * @example
-	 * var point = new Point(12, 6);
-	 * console.log(point % 5); // {x: 2, y: 1}
-	 * 
 	 * @name Point#modulo
 	 * @function
 	 * @param {Number} value
 	 * @return {Point} the integer remainders of dividing the point by the value
 	 *                 as a new point
+	 * 
+	 * @example
+	 * var point = new Point(12, 6);
+	 * console.log(point % 5); // {x: 2, y: 1}
 	 */
 	/**
 	 * The modulo operator returns the integer remainders of dividing the point
 	 * by the supplied value as a new point.
 	 * 
-	 * @example
-	 * var point = new Point(12, 6);
-	 * console.log(point % new Point(5, 2)); // {x: 2, y: 0}
-	 * 
 	 * @name Point#modulo
 	 * @function
 	 * @param {Point} point
 	 * @return {Point} the integer remainders of dividing the points by each
 	 *                 other as a new point
+	 * 
+	 * @example
+	 * var point = new Point(12, 6);
+	 * console.log(point % new Point(5, 2)); // {x: 2, y: 0}
 	 */
 	modulo: function(point) {
 		point = Point.read(arguments);
@@ -485,6 +557,9 @@ var Point = this.Point = Base.extend({
 	 * degrees are in quadrant {@code 3} and angles between 270 and 360 degrees
 	 * are in quadrant {@code 4}.
 	 * 
+	 * @type Number
+	 * @bean
+	 * 
 	 * @example
 	 * var point = new Point({
 	 * 	angle: 10,
@@ -500,9 +575,6 @@ var Point = this.Point = Base.extend({
 	 * 
 	 * point.angle = 280;
 	 * console.log(point.quadrant); // 4
-	 * 
-	 * @type Number
-	 * @bean
 	 */
 	getQuadrant: function() {
 		return this.x >= 0 ? this.y >= 0 ? 1 : 4 : this.y >= 0 ? 2 : 3;
@@ -551,14 +623,14 @@ var Point = this.Point = Base.extend({
 	 * Checks whether the coordinates of the point are equal to that of the
 	 * supplied point.
 	 * 
+	 * @param {Point} point
+	 * @return {Boolean} {@true if the points are equal}
+	 * 
 	 * @example
 	 * var point = new Point(5, 10);
 	 * console.log(point == new Point(5, 10)); // true
 	 * console.log(point == new Point(1, 1)); // false
 	 * console.log(point != new Point(1, 1)); // true
-	 *
-	 * @param {Point} point
-	 * @return {boolean} {@true if the points are equal}
 	 */
 	equals: function(point) {
 		point = Point.read(arguments);
@@ -571,7 +643,7 @@ var Point = this.Point = Base.extend({
 	 * Checks whether the point is inside the boundaries of the rectangle.
 	 * 
 	 * @param {Rectangle} rect the rectangle to check against
-	 * @returns {boolean} {@true if the point is inside the rectangle}
+	 * @returns {Boolean} {@true if the point is inside the rectangle}
 	 */
 	isInside: function(rect) {
 		return rect.contains(this);
@@ -582,7 +654,7 @@ var Point = this.Point = Base.extend({
 	 * 
 	 * @param {Point} point the point to check against
 	 * @param {Number} tolerance the maximum distance allowed
-	 * @returns {boolean} {@true if it is within the given distance}
+	 * @returns {Boolean} {@true if it is within the given distance}
 	 */
 	isClose: function(point, tolerance) {
 		return this.getDistance(point) < tolerance;
@@ -593,7 +665,7 @@ var Point = this.Point = Base.extend({
 	 * another vector.
 	 * 
 	 * @param {Point} point the vector to check against
-	 * @returns {boolean} {@true it is parallel}
+	 * @returns {Boolean} {@true it is parallel}
 	 */
 	isColinear: function(point) {
 		return this.cross(point) < Numerical.TOLERANCE;
@@ -604,7 +676,7 @@ var Point = this.Point = Base.extend({
 	 * (perpendicular) to another vector.
 	 * 
 	 * @param {Point} point the vector to check against
-	 * @returns {boolean} {@true it is orthogonal}
+	 * @returns {Boolean} {@true it is orthogonal}
 	 */
 	isOrthogonal: function(point) {
 		return this.dot(point) < Numerical.TOLERANCE;
@@ -613,7 +685,7 @@ var Point = this.Point = Base.extend({
 	/**
 	 * Checks if this point has both the x and y coordinate set to 0.
 	 * 
-	 * @returns {boolean} {@true both x and y are 0}
+	 * @returns {Boolean} {@true both x and y are 0}
 	 */
 	isZero: function() {
 		return this.x == 0 && this.y == 0;
@@ -623,7 +695,7 @@ var Point = this.Point = Base.extend({
 	 * Checks if this point has an undefined value for at least one of its
 	 * coordinates.
 	 * 
-	 * @returns {boolean} {@true if either x or y are not a number}
+	 * @returns {Boolean} {@true if either x or y are not a number}
 	 */
 	isNaN: function() {
 		return isNaN(this.x) || isNaN(this.y);
@@ -679,7 +751,7 @@ var Point = this.Point = Base.extend({
 	 * 
 	 * @name Point#selected
 	 * @property
-	 * @return {boolean} {@true the point is selected}
+	 * @return {Boolean} {@true the point is selected}
 	 */
 
 	statics: {
@@ -757,14 +829,14 @@ var Point = this.Point = Base.extend({
 	 * Returns a new point with rounded {@link #x} and {@link #y} values. The
 	 * object itself is not modified!
 	 * 
+	 * @name Point#round
+	 * @function
+	 * @return {Point}
+	 * 
 	 * @example
 	 * var point = new Point(10.2, 10.9);
 	 * var roundPoint = point.round();
 	 * console.log(roundPoint); // { x: 10.0, y: 11.0 }
-	 * 
-	 * @name Point#round
-	 * @function
-	 * @return {Point}
 	 */
 
 	/**
@@ -772,14 +844,14 @@ var Point = this.Point = Base.extend({
 	 * specified {@link #x} and {@link #y} values. The object itself is not
 	 * modified!
 	 * 
+	 * @name Point#ceil
+	 * @function
+	 * @return {Point}
+	 * 
 	 * @example
 	 * var point = new Point(10.2, 10.9);
 	 * var ceilPoint = point.ceil();
 	 * console.log(ceilPoint); // { x: 11.0, y: 11.0 }
-	 * 
-	 * @name Point#ceil
-	 * @function
-	 * @return {Point}
 	 */
 
 	/**
@@ -787,28 +859,28 @@ var Point = this.Point = Base.extend({
 	 * specified {@link #x} and {@link #y} values. The object itself is not
 	 * modified!
 	 * 
+	 * @name Point#floor
+	 * @function
+	 * @return {Point}
+	 * 
 	 * @example
 	 * var point = new Point(10.2, 10.9);
 	 * var floorPoint = point.floor();
 	 * console.log(floorPoint); // { x: 10.0, y: 10.0 }
-	 * 
-	 * @name Point#floor
-	 * @function
-	 * @return {Point}
 	 */
 
 	/**
 	 * Returns a new point with the absolute values of the specified {@link #x}
 	 * and {@link #y} values. The object itself is not modified!
 	 * 
+	 * @name Point#abs
+	 * @function
+	 * @return {Point}
+	 * 
 	 * @example
 	 * var point = new Point(-5, 10);
 	 * var absPoint = point.abs();
 	 * console.log(absPoint); // { x: 5.0, y: 10.0 }
-	 * 
-	 * @name Point#abs
-	 * @function
-	 * @return {Point}
 	 */
 
 	return Base.each(['round', 'ceil', 'floor', 'abs'], function(name) {

src/basic/Rectangle.js

@@ -352,7 +352,7 @@ var Rectangle = this.Rectangle = Base.extend({
 	 * that of the supplied rectangle.
 	 * 
 	 * @param {Rectangle} rect
-	 * @return {boolean} {@true if the rectangles are equal}
+	 * @return {Boolean} {@true if the rectangles are equal}
 	 */
 	equals: function(rect) {
 		rect = Rectangle.read(arguments);
@@ -361,7 +361,7 @@ var Rectangle = this.Rectangle = Base.extend({
 	},
 
 	/**
-	 * @return {boolean} {@true the rectangle is empty}
+	 * @return {Boolean} {@true the rectangle is empty}
 	 */
 	isEmpty: function() {
 		return this.width == 0 || this.height == 0;
@@ -387,14 +387,14 @@ var Rectangle = this.Rectangle = Base.extend({
 	 * @name Rectangle#contains
 	 * @function
 	 * @param {Point} point the specified point
-	 * @return {boolean} {@true if the point is inside the rectangle's boundary}
+	 * @return {Boolean} {@true if the point is inside the rectangle's boundary}
 	 */
 	/**
 	 * Tests if the interior of the rectangle entirely contains the specified
 	 * rectangle.
 	 * 
 	 * @param {Rectangle} rect The specified rectangle
-	 * @return {boolean} {@true if the rectangle entirely contains the specified
+	 * @return {Boolean} {@true if the rectangle entirely contains the specified
 	 *                   rectangle}
 	 */
 	contains: function(rect) {
@@ -415,7 +415,7 @@ var Rectangle = this.Rectangle = Base.extend({
 	 * another rectangle.
 	 * 
 	 * @param {Rectangle} rect the specified rectangle
-	 * @return {boolean} {@true if the rectangle and the specified rectangle
+	 * @return {Boolean} {@true if the rectangle and the specified rectangle
 	 *                   intersect each other}
 	 */
 	intersects: function(rect) {

src/basic/Size.js

@@ -19,44 +19,78 @@ var Size = this.Size = Base.extend({
 
 	// DOCS: improve Size class description
 	/**
-	 * Creates a Size object using the coordinates of the given Size object.
+	 * Creates a Size object with the given width and height values.
 	 * 
 	 * @constructor
 	 * @name Size
-	 * @param {Size} size
+	 * @param {Number} width the width
+	 * @param {Number} height the height
+	 * 
+	 * @example
+	 * // Create a size that is 10pt wide and 5pt high
+	 * var size = new Size(10, 5);
+	 * console.log(size.width); // 10
+	 * console.log(size.height); // 5
 	 * 
 	 * @class The Size object is used to describe the size of something, through
 	 * its {@link #width} and {@link #height} properties.
 	 * 
 	 * Sample code:
 	 * <pre>
-	 * // Create a size that is 10pt wide and 5pt height
+	 * // Create a size that is 10pt wide and 5pt high
 	 * var size = new Size(10, 5);
 	 * console.log(size.width); // 10
 	 * console.log(size.height); // 5
 	 * </pre>
 	 */
 	/**
-	 * Creates a Point object using the x and y values of the given Point
+	 * Creates a Size object using the numbers in the given array as
+	 * dimensions.
+	 *
+	 * @name Size#initialize
+	 * @param {array} array
+	 * 
+	 * @example
+	 * // Creating a size of width: 320, height: 240 using an array of numbers:
+	 * var array = [320, 240];
+	 * var size = new Point(array);
+	 * console.log(size.width); // 320
+	 * console.log(size.height); // 240
+	 */
+	/**
+	 * Creates a Size object using the properties in the given object.
+	 *
+	 * @name Size#initialize
+	 * @param {object} object
+	 * 
+	 * @example
+	 * // Creating a size of width: 10, height: 20 using an object literal:
+	 * 
+	 * var size = new Size({
+	 * 	width: 10,
+	 * 	height: 20
+	 * });
+	 * console.log(size.width); // 10
+	 * console.log(size.height); // 20
+	 */
+	/**
+	 * Creates a Size object using the coordinates of the given Size object.
+	 *
+	 * @name Size#initialize
+	 * @param {Size} size
+	 */
+	/**
+	 * Creates a Size object using the x and y values of the given Point
 	 * object.
 	 * 
-	 * Sample code:
+	 * @name Size#initialize
-	 * <code>
+	 * @param {Point} point
+	 * 
+	 * @example
 	 * var point = new Point(50, 50);
 	 * var size = new Size(point);
 	 * console.log(size.width); // 50
 	 * console.log(size.height); // 50
-	 * </code>
-	 * 
-	 * @name Size#initialize
-	 * @param {Point} point
-	 */
-	/**
-	 * Creates a Size object with the given width and height values.
-	 *
-	 * @name Size#initialize
-	 * @param {Number} width the width
-	 * @param {Number} height the height
 	 */
 	initialize: function(arg0, arg1) {
 		if (arg1 !== undefined) {
@@ -117,30 +151,30 @@ var Size = this.Size = Base.extend({
 	 * Returns the addition of the supplied value to the width and height of the
 	 * size as a new size. The object itself is not modified!
 	 * 
-	 * @example
-	 * var size = new Size(5, 10);
-	 * var result = size + 20;
-	 * console.log(result); // { width: 25.0, height: 30.0 }
-	 * 
 	 * @name Size#add
 	 * @function
 	 * @param {Number} number the number to add
 	 * @return {Size} the addition of the size and the value as a new size
+	 * 
+	 * @example
+	 * var size = new Size(5, 10);
+	 * var result = size + 20;
+	 * console.log(result); // { width: 25.0, height: 30.0 }
 	 */
 	/**
 	 * Returns the addition of the width and height of the supplied size to the
 	 * size as a new size. The object itself is not modified!
 	 * 
+	 * @name Size#add
+	 * @function
+	 * @param {Size} size the size to add
+	 * @return {Size} the addition of the two sizes as a new size
+	 * 
 	 * @example
 	 * var size1 = new Size(5, 10);
 	 * var size2 = new Size(10, 20);
 	 * var result = size1 + size2;
 	 * console.log(result); // { width: 15.0, height: 30.0 }
-	 * 
-	 * @name Size#add
-	 * @function
-	 * @param {Size} size the size to add
-	 * @return {Size} the addition of the two sizes as a new size
 	 */
 	add: function(size) {
 		size = Size.read(arguments);
@@ -152,30 +186,30 @@ var Size = this.Size = Base.extend({
 	 * of the size as a new size. The object itself is not modified!
 	 * The object itself is not modified!
 	 * 
-	 * @example
-	 * var size = new Size(10, 20);
-	 * var result = size - 5;
-	 * console.log(result); // { width: 5.0, height: 15.0 }
-	 * 
 	 * @name Size#subtract
 	 * @function
 	 * @param {Number} number the number to subtract
 	 * @return {Size} the subtraction of the size and the value as a new size
+	 * 
+	 * @example
+	 * var size = new Size(10, 20);
+	 * var result = size - 5;
+	 * console.log(result); // { width: 5.0, height: 15.0 }
 	 */
 	/**
 	 * Returns the subtraction of the width and height of the supplied size from
 	 * the size as a new size. The object itself is not modified!
 	 * 
+	 * @name Size#subtract
+	 * @function
+	 * @param {Size} size the size to subtract
+	 * @return {Size} the subtraction of the two sizes as a new size
+	 * 
 	 * @example
 	 * var firstSize = new Size(10, 20);
 	 * var secondSize = new Size(5, 5);
 	 * var result = firstSize - secondSize;
 	 * console.log(result); // { width: 5.0, height: 15.0 }
-	 * 
-	 * @name Size#subtract
-	 * @function
-	 * @param {Size} size the size to subtract
-	 * @return {Size} the subtraction of the two sizes as a new size
 	 */
 	subtract: function(size) {
 		size = Size.read(arguments);
@@ -186,30 +220,30 @@ var Size = this.Size = Base.extend({
 	 * Returns the multiplication of the supplied value with the width and
 	 * height of the size as a new size. The object itself is not modified!
 	 * 
-	 * @example
-	 * var size = new Size(10, 20);
-	 * var result = size * 2;
-	 * console.log(result); // { width: 20.0, height: 40.0 }
-	 * 
 	 * @name Size#multiply
 	 * @function
 	 * @param {Number} number the number to multiply by
 	 * @return {Size} the multiplication of the size and the value as a new size
+	 * 
+	 * @example
+	 * var size = new Size(10, 20);
+	 * var result = size * 2;
+	 * console.log(result); // { width: 20.0, height: 40.0 }
 	 */
 	/**
 	 * Returns the multiplication of the width and height of the supplied size
 	 * with the size as a new size. The object itself is not modified!
 	 * 
+	 * @name Size#multiply
+	 * @function
+	 * @param {Size} size the size to multiply by
+	 * @return {Size} the multiplication of the two sizes as a new size
+	 * 
 	 * @example
 	 * var firstSize = new Size(5, 10);
 	 * var secondSize = new Size(4, 2);
 	 * var result = firstSize * secondSize;
 	 * console.log(result); // { width: 20.0, height: 20.0 }
-	 * 
-	 * @name Size#multiply
-	 * @function
-	 * @param {Size} size the size to multiply by
-	 * @return {Size} the multiplication of the two sizes as a new size
 	 */
 	multiply: function(size) {
 		size = Size.read(arguments);
@@ -220,30 +254,30 @@ var Size = this.Size = Base.extend({
 	 * Returns the division of the supplied value by the width and height of the
 	 * size as a new size. The object itself is not modified!
 	 * 
-	 * @example
-	 * var size = new Size(10, 20);
-	 * var result = size / 2;
-	 * console.log(result); // { width: 5.0, height: 10.0 }
-	 * 
 	 * @name Size#divide
 	 * @function
 	 * @param {Number} number the number to divide by
 	 * @return {Size} the division of the size and the value as a new size
+	 * 
+	 * @example
+	 * var size = new Size(10, 20);
+	 * var result = size / 2;
+	 * console.log(result); // { width: 5.0, height: 10.0 }
 	 */
 	/**
 	 * Returns the division of the width and height of the supplied size by the
 	 * size as a new size. The object itself is not modified!
 	 * 
+	 * @name Size#divide
+	 * @function
+	 * @param {Size} size the size to divide by
+	 * @return {Size} the division of the two sizes as a new size
+	 * 
 	 * @example
 	 * var firstSize = new Size(8, 10);
 	 * var secondSize = new Size(2, 5);
 	 * var result = firstSize / secondSize;
 	 * console.log(result); // { width: 4.0, height: 2.0 }
-	 * 
-	 * @name Size#divide
-	 * @function
-	 * @param {Size} size the size to divide by
-	 * @return {Size} the division of the two sizes as a new size
 	 */
 	divide: function(size) {
 		size = Size.read(arguments);
@@ -254,29 +288,29 @@ var Size = this.Size = Base.extend({
 	 * The modulo operator returns the integer remainders of dividing the size
 	 * by the supplied value as a new size.
 	 * 
-	 * @example
-	 * var size = new Size(12, 6);
-	 * console.log(size % 5); // {width: 2, height: 1}
-	 * 
 	 * @name Size#modulo
 	 * @function
 	 * @param {Number} value
 	 * @return {Size} the integer remainders of dividing the size by the value
 	 *                 as a new size
+	 * 
+	 * @example
+	 * var size = new Size(12, 6);
+	 * console.log(size % 5); // {width: 2, height: 1}
 	 */
 	/**
 	 * The modulo operator returns the integer remainders of dividing the size
 	 * by the supplied size as a new size.
 	 * 
-	 * @example
-	 * var size = new Size(12, 6);
-	 * console.log(size % new Size(5, 2)); // {width: 2, height: 0}
-	 * 
 	 * @name Size#modulo
 	 * @function
 	 * @param {Size} size
 	 * @return {Size} the integer remainders of dividing the sizes by each
 	 *                 other as a new size
+	 * 
+	 * @example
+	 * var size = new Size(12, 6);
+	 * console.log(size % new Size(5, 2)); // {width: 2, height: 0}
 	 */
 	modulo: function(size) {
 		size = Size.read(arguments);
@@ -290,15 +324,15 @@ var Size = this.Size = Base.extend({
 	/**
 	 * Checks whether the width and height of the size are equal to those of the
 	 * supplied size.
+	 *
+	 * @param {Size}
+	 * @return {Boolean}
 	 * 
 	 * @example
 	 * var size = new Size(5, 10);
 	 * console.log(size == new Size(5, 10)); // true
 	 * console.log(size == new Size(1, 1)); // false
 	 * console.log(size != new Size(1, 1)); // true
-	 *
-	 * @param {Size}
-	 * @return {boolean}
 	 */
 	equals: function(size) {
 		size = Size.read(arguments);
@@ -309,7 +343,7 @@ var Size = this.Size = Base.extend({
 	 * {@grouptitle Tests}
 	 * Checks if this size has both the width and height set to 0.
 	 * 
-	 * @return {boolean} {@true both width and height are 0}
+	 * @return {Boolean} {@true both width and height are 0}
 	 */
 	isZero: function() {
 		return this.width == 0 && this.width == 0;
@@ -318,7 +352,7 @@ var Size = this.Size = Base.extend({
 	/**
 	 * Checks if the width or the height of the size are NaN.
 	 * 
-	 * @return {boolean} {@true if the width or height of the size are NaN}
+	 * @return {Boolean} {@true if the width or height of the size are NaN}
 	 */
 	isNaN: function() {
 		return isNaN(this.width) || isNaN(this.height);
@@ -336,16 +370,16 @@ var Size = this.Size = Base.extend({
 		 * Returns a new size object with the smallest {@link #width} and
 		 * {@link #height} of the supplied sizes.
 		 * 
+		 * @static
+		 * @param {Size} size1
+		 * @param {Size} size2
+		 * @returns {Size} The newly created size object
+		 * 
 		 * @example
 		 * var size1 = new Size(10, 100);
 		 * var size2 = new Size(200, 5);
 		 * var minSize = Size.min(size1, size2);
 		 * console.log(minSize); // { width: 10.0, height: 5.0 }
-		 * 
-		 * @static
-		 * @param {Size} size1
-		 * @param {Size} size2
-		 * @returns {Size} The newly created size object
 		 */
 		min: function(size1, size2) {
 			return Size.create(
@@ -357,16 +391,16 @@ var Size = this.Size = Base.extend({
 		 * Returns a new size object with the largest {@link #width} and
 		 * {@link #height} of the supplied sizes.
 		 * 
+		 * @static
+		 * @param {Size} size1
+		 * @param {Size} size2
+		 * @returns {Size} The newly created size object
+		 * 
 		 * @example
 		 * var size1 = new Size(10, 100);
 		 * var size2 = new Size(200, 5);
 		 * var maxSize = Size.max(size1, size2);
 		 * console.log(maxSize); // { width: 200.0, height: 100.0 }
-		 * 
-		 * @static
-		 * @param {Size} size1
-		 * @param {Size} size2
-		 * @returns {Size} The newly created size object
 		 */
 		max: function(size1, size2) {
 			return Size.create(
@@ -378,13 +412,13 @@ var Size = this.Size = Base.extend({
 		 * Returns a size object with random {@link #width} and {@link #height}
 		 * values between {@code 0} and {@code 1}.
 		 * 
+		 * @returns {Size} The newly created size object
+		 * @static
+		 * 
 		 * @example
 		 * var maxSize = new Size(100, 100);
 		 * var randomSize = Size.random();
 		 * var size = maxSize * randomSize;
-		 * 
-		 * @returns {Size} The newly created size object
-		 * @static
 		 */
 		random: function() {
 			return Size.create(Math.random(), Math.random());
@@ -398,14 +432,14 @@ var Size = this.Size = Base.extend({
 	 * Returns a new size with rounded {@link #width} and {@link #height} values.
 	 * The object itself is not modified!
 	 * 
+	 * @name Size#round
+	 * @function
+	 * @return {Size}
+	 * 
 	 * @example
 	 * var size = new Size(10.2, 10.9);
 	 * var roundSize = size.round();
 	 * console.log(roundSize); // { x: 10.0, y: 11.0 }
-	 * 
-	 * @name Size#round
-	 * @function
-	 * @return {Size}
 	 */
 
 	/**
@@ -413,14 +447,14 @@ var Size = this.Size = Base.extend({
 	 * specified {@link #width} and {@link #height} values. The object itself is not
 	 * modified!
 	 * 
+	 * @name Size#ceil
+	 * @function
+	 * @return {Size}
+	 * 
 	 * @example
 	 * var size = new Size(10.2, 10.9);
 	 * var ceilSize = size.ceil();
 	 * console.log(ceilSize); // { x: 11.0, y: 11.0 }
-	 * 
-	 * @name Size#ceil
-	 * @function
-	 * @return {Size}
 	 */
 
 	/**
@@ -428,28 +462,28 @@ var Size = this.Size = Base.extend({
 	 * specified {@link #width} and {@link #height} values. The object itself is not
 	 * modified!
 	 * 
+	 * @name Size#floor
+	 * @function
+	 * @return {Size}
+	 * 
 	 * @example
 	 * var size = new Size(10.2, 10.9);
 	 * var floorSize = size.floor();
 	 * console.log(floorSize); // { x: 10.0, y: 10.0 }
-	 * 
-	 * @name Size#floor
-	 * @function
-	 * @return {Size}
 	 */
 
 	/**
 	 * Returns a new size with the absolute values of the specified {@link #width}
 	 * and {@link #height} values. The object itself is not modified!
 	 * 
+	 * @name Size#abs
+	 * @function
+	 * @return {Size}
+	 * 
 	 * @example
 	 * var size = new Size(-5, 10);
 	 * var absSize = size.abs();
 	 * console.log(absSize); // { x: 5.0, y: 10.0 }
-	 * 
-	 * @name Size#abs
-	 * @function
-	 * @return {Size}
 	 */
 
 	return Base.each(['round', 'ceil', 'floor', 'abs'], function(name) {

src/color/Color.js

@@ -292,7 +292,7 @@ var Color = this.Color = Base.extend(new function() {
 	 * console.log(color.type); // 'rgb'
 	 * </code>
 	 * 
-	 * @type String
+	 * @type String('rgb', 'hsb', 'gray')
 	 * @bean
 	 */
 	getType: function() {

src/color/Gradient.js

@@ -72,7 +72,7 @@ var Gradient = this.Gradient = Base.extend({
 	 * Checks whether the gradient is equal to the supplied gradient.
 	 *
 	 * @param {Gradient} gradient
-	 * @return {boolean} {@true they are equal}
+	 * @return {Boolean} {@true they are equal}
 	 */
 	equals: function(gradient) {
 		if (gradient.type != this.type)

src/item/Group.js

@@ -22,20 +22,34 @@ var Group = this.Group = Item.extend({
 	/**
 	 * Creates a new Group item and places it at the top of the active layer.
 	 * 
-	 * @example
-	 * // Create an empty group:
-	 * var group = new Group();
-	 * // Append a path to the group:
-	 * var line = new Path.Line(new Point(10, 10), new Point(50, 50));
-	 * group.appendTop(line);
-	 * 
-	 * // Create a group containing a path:
-	 * var circle = new Path.Circle(new Point(10, 10), 100);
-	 * var circleGroup = new Group([circle]);
-	 * 
 	 * @param {Array} [children] An optional array of children that will be
 	 * added to the newly created group.
 	 * 
+	 * @example
+	 * // Create an empty group and append a path to the top of its children
+	 * // array:
+	 * 
+	 * // Create an empty group:
+	 * var group = new Group();
+	 * 
+	 * var path = new Path([new Point(10, 10), new Point(50, 50)]);
+	 * path.strokeColor = 'black';
+	 * 
+	 * // Append the path to the group:
+	 * group.appendTop(path);
+	 * 
+	 * // Set the stroke color of all items in the group:
+	 * circleGroup.strokeColor = 'black';
+	 * 
+	 * @example
+	 * // Create a group containing two paths:
+	 * var circle = new Path.Circle(new Point(30, 50), 10);
+	 * var circle2 = new Path.Circle(new Point(50, 50), 10);
+	 * 
+	 * var circleGroup = new Group([circle, circle2]);
+	 * // Set the fill color of all items in the group:
+	 * circleGroup.fillColor = 'black';
+	 * 
 	 * @class A Group is a collection of items. When you transform a Group, its
 	 * children are treated as a single unit without changing their relative
 	 * positions.
@@ -62,7 +76,7 @@ var Group = this.Group = Item.extend({
 	 * When setting to true, the first child in the group is automatically
 	 * defined as the clipping mask.
 	 *
-	 * @type boolean
+	 * @type Boolean
 	 * @bean
 	 */
 	isClipped: function() {

src/item/Item.js

@@ -64,13 +64,13 @@ var Item = this.Item = Base.extend({
 	 * The name of the item. If the item has a name, it can be accessed by name
 	 * through its parent's children list.
 	 * 
+	 * @type String
+	 * @bean
+	 * 
 	 * @example
 	 * var path = new Path();
 	 * path.name = 'example';
 	 * project.activeLayer.children['example'].remove();
-	 * 
-	 * @type String
-	 * @bean
 	 */
 	getName: function() {
 		return this._name;
@@ -98,7 +98,12 @@ var Item = this.Item = Base.extend({
 	 * The item's position within the project. This is the
 	 * {@link Rectangle#center} of the {@link #bounds} rectangle.
 	 * 
+	 * @type Point
+	 * @bean
+	 * 
 	 * @example
+	 * // Changing the position of a path:
+	 * 
 	 * // Create a circle at position { x: 10, y: 10 }
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
 	 * circle.fillColor = 'red';
@@ -111,6 +116,8 @@ var Item = this.Item = Base.extend({
 	 * console.log(circle.position); // { x: 30, y: 30 }
 	 *
 	 * @example
+	 * // Changing the x coordinate of an item's position:
+	 * 
 	 * // Create a circle at position { x: 10, y: 10 }
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
 	 * circle.fillColor = 'red';
@@ -118,9 +125,6 @@ var Item = this.Item = Base.extend({
 	 * // Move the circle 10 points to the right
 	 * circle.position.x += 10;
 	 * console.log(circle.position); // { x: 20, y: 10 }
-	 * 
-	 * @type Point
-	 * @bean
 	 */
 	getPosition: function() {
 		// Cache position value
@@ -141,17 +145,19 @@ var Item = this.Item = Base.extend({
 
 	/**
 	 * The path style of the item.
+	 * 
+	 * @type PathStyle
+	 * @bean
 	 *
 	 * @example
+	 * // Applying several styles to an item in one go, by passing an object
+	 * // to its style property:
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
 	 * circle.style = {
 	 * 	fillColor: new RGBColor(1, 0, 0),
 	 * 	strokeColor: new RGBColor(0, 1, 0),
 	 * 	strokeWidth: 5
 	 * };
-	 * 
-	 * @type PathStyle
-	 * @bean
 	 */
 	getStyle: function() {
 		return this._style;
@@ -170,15 +176,16 @@ var Item = this.Item = Base.extend({
 	 * project. This can be useful for debugging, as it allows you to see the
 	 * construction of paths, position of path curves, individual segment points
 	 * and bounding boxes of symbol and raster items.
+	 *
+	 * @type Boolean
+	 * @bean
 	 * 
 	 * @example
+	 * // Selecting an item:
 	 * console.log(project.selectedItems.length); // 0
 	 * var path = new Path.Circle(new Size(50, 50), 25);
 	 * path.selected = true; // Select the path
-	 * console.log(project.selectedItems.length) // 1
+	 * console.log(project.selectedItems.length); // 1
-	 *
-	 * @type boolean {@true the item is selected}
-	 * @bean
 	 */	
 	isSelected: function() {
 		if (this._children) {
@@ -215,7 +222,7 @@ var Item = this.Item = Base.extend({
 	/**
 	 * Specifies whether the item is locked.
 	 * 
-	 * @type boolean
+	 * @type Boolean
 	 * @default false
 	 * @ignore
 	 */
@@ -225,14 +232,14 @@ var Item = this.Item = Base.extend({
 	 * Specifies whether the item is visible. When set to {@code false}, the
 	 * item won't be drawn.
 	 * 
+	 * @type Boolean
+	 * @default true
+	 * 
 	 * @example
+	 * // Hiding an item:
 	 * var path = new Path.Circle(new Point(50, 50), 20);
 	 * path.fillColor = 'red';
-	 * console.log(path.visible) // true
 	 * path.visible = false; // Hides the path
-	 * 
-	 * @type boolean {@true the item is visible}
-	 * @default true
 	 */
 	visible: true,
 
@@ -241,7 +248,7 @@ var Item = this.Item = Base.extend({
 	 * paths, compound paths, and text frame objects, and only if the item is
 	 * already contained within a clipping group.
 	 * 
-	 * @type boolean
+	 * @type Boolean
 	 * @default false
 	 * @bean
 	 */
@@ -260,15 +267,14 @@ var Item = this.Item = Base.extend({
 	/**
 	 * The blend mode of the item.
 	 * 
-	 * @example
-	 * var circle = new Path.Circle(new Point(50, 50), 10);
-	 * circle.fillColor = 'red';
-	 * 
-	 * // Change the blend mode of the path item:
-	 * circle.blendMode = 'multiply';
-	 * 
 	 * @type String('normal','screen','multiply','difference','src-in','add','overlay','hard-light','dodge','burn','darken','lighten','exclusion')
 	 * @default 'normal'
+	 * 
+	 * @example
+	 * // Setting an item's blend mode to 'multiply':
+	 * var circle = new Path.Circle(new Point(50, 50), 10);
+	 * circle.fillColor = 'red';
+	 * circle.blendMode = 'multiply';
 	 */
 	blendMode: 'normal',
 
@@ -276,11 +282,11 @@ var Item = this.Item = Base.extend({
 	 * The opacity of the item as a value between 0 and 1.
 	 * 
 	 * @example
+	 * // Making an item 50% transparent:
+	 * 
 	 * // Create a circle at position { x: 50, y: 50 } 
 	 * var circle = new Path.Circle(new Point(50, 50), 20);
 	 * circle.fillColor = 'red';
-	 * 
-	 * // Change the opacity of the circle to 50%:
 	 * circle.opacity = 0.5;
 	 * 
 	 * @type Number
@@ -320,6 +326,9 @@ var Item = this.Item = Base.extend({
 	/**
 	 * The item that this item is contained within.
 	 * 
+	 * @type Item
+	 * @bean
+	 * 
 	 * @example
 	 * var path = new Path();
 	 * // New items are placed in the active layer:
@@ -329,9 +338,6 @@ var Item = this.Item = Base.extend({
 	 * group.appendTop(path);
 	 * // Now the parent of the path has become the group:
 	 * console.log(path.parent == group); // true
-	 * 
-	 * @type Item
-	 * @bean
 	 */
 	getParent: function() {
 		return this._parent;
@@ -340,6 +346,9 @@ var Item = this.Item = Base.extend({
 	/**
 	 * The children items contained within this item. Items that define a
 	 * {@link #name} can also be accessed by name.
+	 * 
+	 * @type Item[]
+	 * @bean
 	 *
 	 * @example
 	 * var path = new Path();
@@ -352,9 +361,6 @@ var Item = this.Item = Base.extend({
 	 * path.name = 'example';
 	 * // Now the path can also be accessed by name:
 	 * console.log(group.children['example'] == path); // true
-	 * 
-	 * @type Item[]
-	 * @bean
 	 */
 	getChildren: function() {
 		return this._children;
@@ -455,7 +461,7 @@ var Item = this.Item = Base.extend({
 	* Removes the item from the project. If the item has children, they are also
 	* removed.
 	* 
-	* @return {boolean} {@true the item was removed}
+	* @return {Boolean} {@true the item was removed}
 	*/
 	remove: function() {
 		if (this.isSelected())
@@ -466,7 +472,7 @@ var Item = this.Item = Base.extend({
 	/**
 	 * Removes all of the item's children (if any).
 	 * 
-	 * @return {boolean} {@true removing was successful}
+	 * @return {Boolean} {@true removing was successful}
 	 */
 	removeChildren: function() {
 		var removed = false;
@@ -535,7 +541,7 @@ var Item = this.Item = Base.extend({
 	/**
 	 * Reverses the order of this item's children
 	 * 
-	 * @return {boolean} {@true the children were removed}
+	 * @return {Boolean} {@true the children were removed}
 	 */
 	reverseChildren: function() {
 		if (this._children) {
@@ -575,7 +581,7 @@ var Item = this.Item = Base.extend({
 	 * {@grouptitle Tests}
 	 * Checks if the item contains any children items.
 	 * 
-	 * @return {boolean} {@true it has one or more children}
+	 * @return {Boolean} {@true it has one or more children}
 	 */
 	hasChildren: function() {
 		return this._children && this._children.length > 0;
@@ -586,7 +592,7 @@ var Item = this.Item = Base.extend({
 	/**
 	 * Checks whether the item is editable.
 	 * 
-	 * @return {boolean} {@true when neither the item, nor its parents are
+	 * @return {Boolean} {@true when neither the item, nor its parents are
 	 * locked or hidden}
 	 * @ignore
 	 */
@@ -603,7 +609,7 @@ var Item = this.Item = Base.extend({
 	/**
 	 * Checks whether the item is valid, i.e. it hasn't been removed.
 	 * 
-	 * @return {boolean} {@true the item is valid}
+	 * @return {Boolean} {@true the item is valid}
 	 */
 	// TODO: isValid / checkValid
 
@@ -638,7 +644,7 @@ var Item = this.Item = Base.extend({
 	 * of the project.
 	 * 
 	 * @param {Item} item The item to check against
-	 * @return {boolean} {@true if it is above the specified item}
+	 * @return {Boolean} {@true if it is above the specified item}
 	 */
 	isAbove: function(item) {
 		return this._getOrder(item) == -1;
@@ -649,7 +655,7 @@ var Item = this.Item = Base.extend({
 	 * the project.
 	 * 
 	 * @param {Item} item The item to check against
-	 * @return {boolean} {@true if it is below the specified item}
+	 * @return {Boolean} {@true if it is below the specified item}
 	 */
 	isBelow: function(item) {
 		return this._getOrder(item) == 1;
@@ -660,7 +666,7 @@ var Item = this.Item = Base.extend({
 	 * Checks whether the specified item is the parent of the item.
 	 * 
 	 * @param {Item} item The item to check against
-	 * @return {boolean} {@true if it is the parent of the item}
+	 * @return {Boolean} {@true if it is the parent of the item}
 	 */
 	isParent: function(item) {
 		return this._parent == item;
@@ -670,7 +676,7 @@ var Item = this.Item = Base.extend({
 	 * Checks whether the specified item is a child of the item.
 	 * 
 	 * @param {Item} item The item to check against
-	 * @return {boolean} {@true it is a child of the item}
+	 * @return {Boolean} {@true it is a child of the item}
 	 */
 	isChild: function(item) {
 		return item && item._parent == this;
@@ -680,7 +686,7 @@ var Item = this.Item = Base.extend({
 	 * Checks if the item is contained within the specified item.
 	 * 
 	 * @param {Item} item The item to check against
-	 * @return {boolean} {@true if it is inside the specified item}
+	 * @return {Boolean} {@true if it is inside the specified item}
 	 */
 	// TODO: Consider naming this isInside?
 	isDescendant: function(item) {
@@ -696,7 +702,7 @@ var Item = this.Item = Base.extend({
 	 * Checks if the item is an ancestor of the specified item.
 	 * 
 	 * @param {Item} item the item to check against
-	 * @return {boolean} {@true if the item is an ancestor of the specified
+	 * @return {Boolean} {@true if the item is an ancestor of the specified
 	 * item}
 	 */
 	// TODO: Consider naming this contains?
@@ -708,7 +714,7 @@ var Item = this.Item = Base.extend({
 	 * Checks whether the item is grouped with the specified item.
 	 * 
 	 * @param {Item} item
-	 * @return {boolean} {@true if the items are grouped together}
+	 * @return {Boolean} {@true if the items are grouped together}
 	 */
 	isGroupedWith: function(item) {
 		var parent = this._parent;
@@ -811,7 +817,7 @@ var Item = this.Item = Base.extend({
 	 * var circle = new Path.Circle(new Point(50, 50), 10);
 	 * 
 	 * // Set the stroke color of the circle to RGB red:
-	 * circle.strokeColor = new RGB(1, 0, 0);
+	 * circle.strokeColor = new RGBColor(1, 0, 0);
 	 * 
 	 * @property
 	 * @name Item#strokeColor
@@ -892,18 +898,20 @@ var Item = this.Item = Base.extend({
 	/**
 	 * {@grouptitle Fill Style}
 	 * 
-	 * The fill color.
+	 * The fill color of the item.
+	 * 
+	 * @property
+	 * @name Item#fillColor
+	 * @type RGBColor|HSBColor|GrayColor
 	 * 
 	 * @example
+	 * // Setting the fill color of a path to red:
+	 * 
 	 * // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
 	 * var circle = new Path.Circle(new Point(50, 50), 10);
 	 * 
 	 * // Set the fill color of the circle to RGB red:
 	 * circle.fillColor = new RGBColor(1, 0, 0, );
-	 * 
-	 * @property
-	 * @name Item#fillColor
-	 * @type RGBColor|HSBColor|GrayColor
 	 */
 
 	// DOCS: document the different arguments that this function can receive.
@@ -913,35 +921,46 @@ var Item = this.Item = Base.extend({
 	 * Scales the item by the given value from its center point, or optionally
 	 * by a supplied point.
 	 * 
+	 * @name Item#scale
+	 * @function
+	 * @param {Number} scale the scale factor
+	 * @param {Point} [center=the center point of the item]
+	 * 
 	 * @example
+	 * // Scaling an item from its center point:
+	 * 
 	 * // Create a circle at position { x: 10, y: 10 } 
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
 	 * console.log(circle.bounds.width); // 20
 	 * 
-	 * // Scale the path by 200% around its center point
+	 * // Scale the path by 200% from its center point
 	 * circle.scale(2);
 	 * 
 	 * console.log(circle.bounds.width); // 40
 	 * 
 	 * @example
+	 * // Scaling an item from a specific point:
+	 * 
 	 * // Create a circle at position { x: 10, y: 10 } 
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
 	 * 
 	 * // Scale the path 200% from its bottom left corner
 	 * circle.scale(2, circle.bounds.bottomLeft);
-	 * 
-	 * @name Item#scale
-	 * @function
-	 * @param {Number} scale the scale factor
-	 * @param {Point} [center=the center point of the item]
 	 */
 	/**
 	 * Scales the item by the given values from its center point, or optionally
 	 * by a supplied point.
 	 * 
+	 * @param {Number} sx the horizontal scale factor
+	 * @param {Number} sy the vertical scale factor
+	 * @param {Point} [center=the center point of the item]
+	 * 
 	 * @example
+	 * // Scaling an item horizontally by 200%:
+	 * 
 	 * // Create a circle at position { x: 10, y: 10 } 
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
+	 * circle.fillColor = 'black';
 	 * console.log(circle.bounds.width); // 20
 	 * 
 	 * // Scale the path horizontally by 200%
@@ -950,15 +969,14 @@ var Item = this.Item = Base.extend({
 	 * console.log(circle.bounds.width); // 40
 	 * 
 	 * @example
+	 * // Scaling an item horizontally by 200% from its bottom left corner:
+	 * 
 	 * // Create a circle at position { x: 10, y: 10 } 
 	 * var circle = new Path.Circle(new Point(10, 10), 10);
+	 * circle.fillColor = 'black';
 	 * 
 	 * // Scale the path 200% horizontally from its bottom left corner
 	 * circle.scale(1, 2, circle.bounds.bottomLeft);
-	 * 
-	 * @param {Number} sx the horizontal scale factor
-	 * @param {Number} sy the vertical scale factor
-	 * @param {Point} [center=the center point of the item]
 	 */
 	scale: function(sx, sy /* | scale */, center) {
 		// See Matrix#scale for explanation of this:
@@ -1209,7 +1227,7 @@ var Item = this.Item = Base.extend({
 		 * 
 		 * @function
 		 * @param {Item} item The item above which it should be moved
-		 * @return {boolean} {@true it was moved}
+		 * @return {Boolean} {@true it was moved}
 		 */
 		moveAbove: move(true),
 
@@ -1218,7 +1236,7 @@ var Item = this.Item = Base.extend({
 		 *
 		 * @function
 		 * @param {Item} item the item below which it should be moved
-		 * @return {boolean} {@true it was moved}
+		 * @return {Boolean} {@true it was moved}
 		 */
 		moveBelow: move(false)
 	};

src/item/Layer.js

@@ -25,13 +25,12 @@ var Layer = this.Layer = Group.extend({
 	 * {@link Project#layers} array. The newly created layer will be activated,
 	 * so all newly created items will be placed within it.
 	 * 
-	 * @example
-	 * var layer = new Layer();
-	 * layer.name = 'the new layer';
-	 * 
 	 * @param {Array} [children] An optional array of items that will be
 	 * added to the newly created layer.
 	 * 
+	 * @example
+	 * var layer = new Layer();
+	 * 
 	 * @class The Layer item represents a layer in a Paper.js project.
 	 * 
 	 * The layer which is currently active can be accessed through

src/item/PathStyle.js

@@ -58,11 +58,11 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
 		 * <pre>
 		 * var circleStyle = {
 		 * 	fillColor: new RGBColor(1, 0, 0),
-		 * 	strokeColor: new GrayColor(1),
+		 * 	strokeColor: 'black',
 		 * 	strokeWidth: 5
 		 * };
 		 * 
-		 * var path = new Path.Circle(new Point(50, 50), 50);
+		 * var path = new Path.Circle(new Point(50, 50), 30);
 		 * path.style = circleStyle;
 		 * </pre>
 		 */
@@ -157,46 +157,57 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
  * 
  * The color of the stroke.
  * 
- * @example
- * // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
- * var circle = new Path.Circle(new Point(50, 50), 10);
- * 
- * // Set the stroke color of the circle to RGB red:
- * circle.strokeColor = new RGB(1, 0, 0);
- * 
  * @property
  * @name PathStyle#strokeColor
  * @type RGBColor|HSBColor|GrayColor
+ * 
+ * @example
+ * // Setting an item's stroke color:
+ * 
+ * // Create a circle shaped path at { x: 50, y: 50 }
+ * // with a radius of 10:
+ * var circle = new Path.Circle(new Point(50, 50), 10);
+ * 
+ * // Set its stroke color to RGB red:
+ * circle.strokeColor = new RGBColor(1, 0, 0);
  */
 
 /**
  * The width of the stroke.
  * 
- * @example
- * // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
- * var circle = new Path.Circle(new Point(50, 50), 10);
- * 
- * // Set the stroke width of the circle to 3pt:
- * circle.strokeWidth = 3;
- * 
  * @property
  * @name PathStyle#strokeWidth
+ * @default 1
  * @type Number
+ * 
+ * @example
+ * // Setting an item's stroke width:
+ * 
+ * // Create a circle shaped path at { x: 50, y: 50 }
+ * // with a radius of 10:
+ * var circle = new Path.Circle(new Point(50, 50), 10);
+ * 
+ * // Set its stroke width to 3pt:
+ * circle.strokeWidth = 3;
  */
 
 /**
  * The cap of the stroke.
  * 
+ * @property
+ * @name PathStyle#strokeCap
+ * @default 'butt'
+ * @type String('round', 'square', 'butt')
+ * 
  * @example
+ * // Setting an item's stroke color:
+ * 
  * // Create a line from { x: 0, y: 50 } to { x: 50, y: 50 };
  * var line = new Path.Line(new Point(0, 50), new Point(50, 50));
+ * line.strokeColor = 'black';
  * 
  * // Set the stroke cap of the line to be round:
  * line.strokeCap = 'round';
- * 
- * @property
- * @name PathStyle#strokeCap
- * @type String('round', 'square', 'butt')
  */
 
 /**
@@ -204,6 +215,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
  * 
  * @property
  * @name PathStyle#strokeJoin
+ * @default 'miter'
  * @type String ('miter', 'round', 'bevel')
  */
 
@@ -212,6 +224,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
 //  * 
 //  * @property
 //  * @name PathStyle#dashOffset
+//  * @default 0
 //  * @type Number
 //  */
 
@@ -229,6 +242,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
 //  * 
 //  * @property
 //  * @name PathStyle#dashArray
+//  * @default []
 //  * @type Array
 //  */
 
@@ -237,6 +251,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
  * 
  * @property
  * @name PathStyle#miterLimit
+ * @default 10
  * @type Number
  */
 
@@ -245,14 +260,17 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
  * 
  * The fill color.
  * 
- * @example
- * // Create a circle shaped path at { x: 50, y: 50 } with a radius of 10:
- * var circle = new Path.Circle(new Point(50, 50), 10);
- * 
- * // Set the fill color of the circle to RGB red:
- * circle.fillColor = new RGBColor(1, 0, 0, );
- * 
  * @property
  * @name PathStyle#fillColor
  * @type RGBColor|HSBColor|GrayColor
+ * 
+ * @example
+ * // Setting the fill color of an item:
+ * 
+ * // Create a circle shaped path at { x: 50, y: 50 }
+ * // with a radius of 10:
+ * var circle = new Path.Circle(new Point(50, 50), 10);
+ * 
+ * // Set its fill color to RGB red:
+ * circle.fillColor = new RGBColor(1, 0, 0, );
  */

src/item/PlacedSymbol.js

@@ -22,7 +22,13 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
 	/**
 	 * Creates a new PlacedSymbol Item.
 	 * 
+	 * @param {Symbol} symbol the symbol to place
+	 * @param {Point|Matrix} matrixOrOffset the center point of the placed
+	 * symbol or a {@link Matrix} transformation to transform the placed symbol
+	 * with.
+	 * 
 	 * @example
+	 * // Placing 100 instances of a symbol:
 	 * var path = new Path.Star(new Point(0, 0), 6, 5, 13);
 	 * path.style = {
 	 *     fillColor: 'white',
@@ -49,13 +55,8 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
 	 *     instance.scale(0.25 + Math.random() * 0.75);
 	 * }
 	 * 
-	 * @param {Symbol} symbol the symbol to place
+	 * @class A PlacedSymbol represents an instance of a symbol which has been
-	 * @param {Point|Matrix} matrixOrOffset the center point of the placed
+	 * placed in a Paper.js project.
-	 * symbol or a {@link Matrix} transformation to transform the placed symbol
-	 * with.
-	 * 
-	 * @class A PlacedSymbol represents a symbol which has been placed in a
-	 * Paper.js project.
 	 *
 	 * @extends Item
 	 * @constructs PlacedSymbol
@@ -71,7 +72,7 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
 	},
 
 	/**
-	 * The symbol contained within the placed symbol.
+	 * The symbol that the placed symbol refers to:
 	 *
 	 * @name PlacedSymbol#symbol
 	 * @type Symbol

src/path/CompoundPath.js

@@ -22,6 +22,16 @@ var CompoundPath = this.CompoundPath = PathItem.extend({
 	 * 
 	 * @constructs CompoundPath
 	 * @param {Array} [paths] the paths to place within the compound path.
+	 * 
+	 * @example
+	 * // Create a donut shaped compound path:
+	 * var circle = new Path.Circle(new Point(50, 50), 30);
+	 * var innerCircle = new Path.Circle(new Point(50, 50), 10);
+	 * var compoundPath = new CompoundPath([circle, innerCircle]);
+	 * compoundPath.fillColor = 'red';
+	 * 
+	 * // Move the inner circle 5pt to the right:
+	 * compoundPath.children[1].position.x += 5;
 	 *
 	 * @class A compound path contains two or more paths, holes are drawn
 	 * where the paths overlap. All the paths in a compound path take on the
@@ -186,7 +196,7 @@ var CompoundPath = this.CompoundPath = PathItem.extend({
 	 * @name CompoundPath#arcTo
 	 * @function
 	 * @param {Point} to
-	 * @param {boolean} [clockwise=true]
+	 * @param {Boolean} [clockwise=true]
 	 */
 
 	// DOCS: document CompoundPath#lineBy

src/path/Curve.js

@@ -182,7 +182,7 @@ var Curve = this.Curve = Base.extend({
 	/**
 	 * Specifies whether the handles of the curve are selected.
 	 *
-	 * @type boolean
+	 * @type Boolean
 	 * @bean
 	 */
 	isSelected: function() {
@@ -234,19 +234,19 @@ var Curve = this.Curve = Base.extend({
 	 * Checks if this curve is linear, meaning it does not define any curve
 	 * handle.
 
-	 * @return {boolean} {@true the curve is linear}
+	 * @return {Boolean} {@true the curve is linear}
 	 */
 	isLinear: function() {
 		return this._segment1._handleOut.isZero()
 				&& this._segment2._handleIn.isZero();
 	},
 
-	// PORT: Add support for start parameter to Scriptographer
+	// PORT: Add support for start parameter to Sg
 	// DOCS: document Curve#getParameter(length, start)
 	/**
 	 * @param {Number} length
 	 * @param {Number} [start]
-	 * @return {boolean} {@true the curve is linear}
+	 * @return {Boolean} {@true the curve is linear}
 	 */
 	getParameter: function(length, start) {
 		var args = this.getCurveValues();
@@ -328,7 +328,7 @@ var Curve = this.Curve = Base.extend({
 			x, y;
 
 		// Handle special case at beginning / end of curve
-		// PORT: Change in Scriptographer too, so 0.000000000001 won't be
+		// PORT: Change in Sg too, so 0.000000000001 won't be
 		// required anymore
 		if (t == 0 || t == 1) {
 			var point;

src/path/Path.Constructors.js

@@ -157,7 +157,7 @@ Path.inject({ statics: new function() {
 		* Creates an oval shaped Path Item.
 		 * 
 		 * @param {Rectangle} rect
-		 * @param {boolean} [circumscribed=false] if this is set to true the
+		 * @param {Boolean} [circumscribed=false] if this is set to true the
 		 *        oval shaped path will be created so the rectangle fits into
 		 *        it. If it's set to false the oval path will fit within the
 		 *        rectangle.

src/path/Path.js

@@ -22,20 +22,21 @@ var Path = this.Path = PathItem.extend({
 	/**
 	 * Creates a new Path item and places it at the top of the active layer.
 	 * 
-	 * @example
-	 * var firstSegment = new Segment(30, 30);
-	 * var secondSegment = new Segment(100, 100);
-	 * var path = new Path([firstSegment, secondSegment]);
-	 * path.strokeColor = 'black';
-	 * 
-	 * @example
-	 * var path = new Path();
-	 * path.strokeColor = 'black';
-	 * path.moveTo(30, 30);
-	 * path.lineTo(100, 100);
-	 * 
 	 * @param {Segment[]} [segments] An optional array of segments (or points to be
 	 * converted to segments) that will be added to the path.
+	 *
+	 * @example
+	 * // Create an empty path and add segments to it:
+	 * var path = new Path();
+	 * path.strokeColor = 'black';
+	 * path.add(new Point(30, 30));
+	 * path.add(new Point(100, 100));
+	 * 
+	 * @example
+	 * // Create a path with two segments:
+	 * var segments = [new Point(30, 30), new Point(100, 100)];
+	 * var path = new Path(segments);
+	 * path.strokeColor = 'black';
 	 * 
 	 * @class The Path item represents a path in a Paper.js project.
 	 * @extends PathItem
@@ -326,15 +327,16 @@ var Path = this.Path = PathItem.extend({
 	 * Adds an array of segments (or types that can be converted to segments)
 	 * to the end of the {@link #segments} array.
 	 * 
+	 * @param {Segment[]} segments
+	 * @return {Segment[]} an array of the added segments. These segments are
+	 * not necessarily the same objects, e.g. if the segment to be added already
+	 * belongs to another path.
+	 * 
 	 * @example
 	 * var path = new Path();
 	 * path.strokeColor = 'black';
 	 * var points = [new Point(10, 10), new Point(50, 50)];
 	 * path.addSegments(points);
-	 * @param {Segment[]} segments
-	 * @return {Segment[]} an array of the added segments. These segments are
-	 * not necessarily the same objects, e.g. if the segment to be added already
-	 * belongs to another path.
 	 */
 	addSegments: function(segments) {
 		return this._add(Segment.readAll(segments));
@@ -436,7 +438,7 @@ var Path = this.Path = PathItem.extend({
 	/**
 	 * Specifies whether all segments of the path are selected.
 	 * 
-	 * @type boolean
+	 * @type Boolean
 	 * @bean
 	 */
 	isFullySelected: function() {
@@ -455,7 +457,7 @@ var Path = this.Path = PathItem.extend({
 	/**
 	 * Specifies whether the path is oriented clock-wise.
 	 * 
-	 * @type boolean
+	 * @type Boolean
 	 * @bean
 	 */
 	isClockwise: function() {
@@ -596,7 +598,7 @@ var Path = this.Path = PathItem.extend({
 	// DOCS: document Path#getLocationAt
 	/**
 	 * @param {Number} offset
-	 * @param {boolean} [isParameter=false]
+	 * @param {Boolean} [isParameter=false]
 	 */
 	getLocationAt: function(offset, isParameter) {
 		var curves = this.getCurves(),
@@ -629,7 +631,7 @@ var Path = this.Path = PathItem.extend({
 	 * Get the point of the path at the given offset.
 	 * 
 	 * @param {Number} offset
-	 * @param {boolean} [isParameter=false]
+	 * @param {Boolean} [isParameter=false]
 	 * @return {Point} the point at the given offset
 	 */
 	getPointAt: function(offset, isParameter) {
@@ -642,7 +644,7 @@ var Path = this.Path = PathItem.extend({
 	 * point.
 	 * 
 	 * @param {Number} offset
-	 * @param {boolean} [isParameter=false]
+	 * @param {Boolean} [isParameter=false]
 	 * @return {Point} the tangent vector at the given offset
 	 */
 	getTangentAt: function(offset, isParameter) {
@@ -654,7 +656,7 @@ var Path = this.Path = PathItem.extend({
 	 * Get the normal to the path at the given offset as a vector point.
 	 * 
 	 * @param {Number} offset
-	 * @param {boolean} [isParameter=false]
+	 * @param {Boolean} [isParameter=false]
 	 * @return {Point} the normal vector at the given offset
 	 */
 	getNormalAt: function(offset, isParameter) {
@@ -1040,7 +1042,7 @@ var Path = this.Path = PathItem.extend({
 		// DOCS: document Path#arcTo
 		/**
 		 * @param {Point} to
-		 * @param {boolean} [clockwise=true]
+		 * @param {Boolean} [clockwise=true]
 		 */
 		arcTo: function(to, clockwise) {
 			// Get the start point:

src/path/Segment.js

@@ -21,6 +21,16 @@ var Segment = this.Segment = Base.extend({
 	/**
 	 * Creates a new Segment object.
 	 * 
+	 * @name Segment
+	 * @constructor
+	 * @param {Point} [point={x: 0, y: 0}] the anchor point of the segment
+	 * @param {Point} [handleIn={x: 0, y: 0}] the handle point relative to the
+	 *        anchor point of the segment that describes the in tangent of the
+	 *        segment.
+	 * @param {Point} [handleOut={x: 0, y: 0}] the handle point relative to the
+	 *        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);
@@ -33,16 +43,7 @@ var Segment = this.Segment = Base.extend({
 	 *
 	 * var path = new Path();
 	 * path.segments = [firstSegment, secondSegment];
-	 * 
+	 * path.strokeColor = 'black';
-	 * @param {Point} [point={x: 0, y: 0}] the anchor point of the segment
-	 * @param {Point} [handleIn={x: 0, y: 0}] the handle point relative to the
-	 *        anchor point of the segment that describes the in tangent of the
-	 *        segment.
-	 * @param {Point} [handleOut={x: 0, y: 0}] the handle point relative to the
-	 *        anchor point of the segment that describes the out tangent of the
-	 *        segment.
-	 * @name Segment
-	 * @constructor
 	 * 
 	 * @class The Segment object represents a part of a path which is
 	 * described by the {@link Path#segments} array. Every segment of a
@@ -170,6 +171,73 @@ var Segment = this.Segment = Base.extend({
 			? null : this._handleOut;
 	},
 
+	_isSelected: function(point) {
+		var state = this._selectionState;
+		return point == this._point ? !!(state & SelectionState.POINT)
+			: point == this._handleIn ? !!(state & SelectionState.HANDLE_IN)
+			: point == this._handleOut ? !!(state & SelectionState.HANDLE_OUT)
+			: false;
+	},
+
+	_setSelected: function(point, selected) {
+		var path = this._path,
+			selected = !!selected, // convert to boolean
+			state = this._selectionState,
+			wasSelected = !!state,
+			// For performance reasons use array indices to access the various
+			// selection states: 0 = point, 1 = handleIn, 2 = handleOut
+			selection = [
+				!!(state & SelectionState.POINT),
+				!!(state & SelectionState.HANDLE_IN),
+				!!(state & SelectionState.HANDLE_OUT)
+			];
+		if (point == this._point) {
+			if (selected) {
+				// We're selecting point, deselect the handles
+				selection[1] = selection[2] = false;
+			} else {
+				var previous = this.getPrevious(),
+					next = this.getNext();
+				// When deselecting a point, the handles get selected instead
+				// depending on the selection state of their neighbors.
+				selection[1] = previous && (previous._point.isSelected()
+						|| previous._handleOut.isSelected());
+				selection[2] = next && (next._point.isSelected()
+						|| next._handleIn.isSelected());
+			}
+			selection[0] = selected;
+		} else {
+			var index = point == this._handleIn ? 1 : 2;
+			if (selection[index] != selected) {
+				// When selecting handles, the point get deselected.
+				if (selected)
+					selection[0] = false;
+				selection[index] = selected;
+			}
+		}
+		this._selectionState = (selection[0] ? SelectionState.POINT : 0)
+				| (selection[1] ? SelectionState.HANDLE_IN : 0)
+				| (selection[2] ? SelectionState.HANDLE_OUT : 0);
+		// If the selection state of the segment has changed, we need to let
+		// it's path know and possibly add or remove it from
+		// project._selectedItems
+		if (path && wasSelected != !!this._selectionState)
+			path._updateSelection(this);
+	},
+
+	/**
+	 * Specifies whether the {@link #point} of the segment is selected.
+	 * @type Boolean
+	 * @bean
+	 */
+	isSelected: function() {
+		return this._isSelected(this._point);
+	},
+
+	setSelected: function(selected) {
+		this._setSelected(this._point, selected);
+	},
+
 	/**
 	 * {@grouptitle Hierarchy}
 	 * 
@@ -240,73 +308,6 @@ var Segment = this.Segment = Base.extend({
 				|| this._path._closed && segments[segments.length - 1]) || null;
 	},
 
-	_isSelected: function(point) {
-		var state = this._selectionState;
-		return point == this._point ? !!(state & SelectionState.POINT)
-			: point == this._handleIn ? !!(state & SelectionState.HANDLE_IN)
-			: point == this._handleOut ? !!(state & SelectionState.HANDLE_OUT)
-			: false;
-	},
-
-	_setSelected: function(point, selected) {
-		var path = this._path,
-			selected = !!selected, // convert to boolean
-			state = this._selectionState,
-			wasSelected = !!state,
-			// For performance reasons use array indices to access the various
-			// selection states: 0 = point, 1 = handleIn, 2 = handleOut
-			selection = [
-				!!(state & SelectionState.POINT),
-				!!(state & SelectionState.HANDLE_IN),
-				!!(state & SelectionState.HANDLE_OUT)
-			];
-		if (point == this._point) {
-			if (selected) {
-				// We're selecting point, deselect the handles
-				selection[1] = selection[2] = false;
-			} else {
-				var previous = this.getPrevious(),
-					next = this.getNext();
-				// When deselecting a point, the handles get selected instead
-				// depending on the selection state of their neighbors.
-				selection[1] = previous && (previous._point.isSelected()
-						|| previous._handleOut.isSelected());
-				selection[2] = next && (next._point.isSelected()
-						|| next._handleIn.isSelected());
-			}
-			selection[0] = selected;
-		} else {
-			var index = point == this._handleIn ? 1 : 2;
-			if (selection[index] != selected) {
-				// When selecting handles, the point get deselected.
-				if (selected)
-					selection[0] = false;
-				selection[index] = selected;
-			}
-		}
-		this._selectionState = (selection[0] ? SelectionState.POINT : 0)
-				| (selection[1] ? SelectionState.HANDLE_IN : 0)
-				| (selection[2] ? SelectionState.HANDLE_OUT : 0);
-		// If the selection state of the segment has changed, we need to let
-		// it's path know and possibly add or remove it from
-		// project._selectedItems
-		if (path && wasSelected != !!this._selectionState)
-			path._updateSelection(this);
-	},
-
-	/**
-	 * Specifies whether the {@link #point} of the segment is selected.
-	 * @type Boolean
-	 * @bean
-	 */
-	isSelected: function() {
-		return this._isSelected(this._point);
-	},
-
-	setSelected: function(selected) {
-		this._setSelected(this._point, selected);
-	},
-
 	/**
 	 * Returns the reversed the segment, without modifying the segment itself.
 	 * @return {Segment} the reversed segment

src/project/Project.js

@@ -65,6 +65,25 @@ var Project = this.Project = Base.extend({
 	 * 
 	 * @type PathStyle
 	 * @bean
+	 * 
+	 * @example
+	 * project.currentStyle = {
+	 * 	fillColor: 'red',
+	 * 	strokeColor: 'black',
+	 * 	strokeWidth: 5
+	 * }
+	 * 
+	 * // The following path will take over all style properties of
+	 * // the current style:
+	 * var path = new Path.Circle(new Point(50, 50), 30);
+	 * console.log(path.strokeWidth); // 5
+	 * 
+	 * @example
+	 * project.currentStyle.fillColor = 'red';
+	 * 
+	 * // The following path will take over the fill color we just set:
+	 * var path = new Path.Circle(new Point(50, 50), 30);
+	 * console.log(path.fillColor); // RGBColor(1, 0, 0)
 	 */
 	getCurrentStyle: function() {
 		return this._currentStyle;

src/project/Symbol.js

@@ -28,15 +28,7 @@ var Symbol = this.Symbol = Base.extend({
 	 * @name Symbol
 	 * @constructor
 	 * 
-	 * @class Symbols allow you to place multiple instances of an item in your
+	 * @example
-	 *        project. This can save memory, since all instances of a symbol
-	 *        simply refer to the original item and it can speed up moving
-	 *        around complex objects, since internal properties such as segment
-	 *        lists and gradient positions don't need to be updated with every
-	 *        transformation.
-	 * 
-	 * Sample code:
-	 * <pre>
 	 * var circlePath = new Path.Circle(new Point(100, 100), 50);
 	 * circlePath.fillColor = 'red';
 	 * 
@@ -45,10 +37,18 @@ var Symbol = this.Symbol = Base.extend({
 	 * // The original item is still contained in the document:
 	 * circlePath.remove();
 	 * 
-	 * // To place instances of the symbol in the document:
+	 * // Place an instance of the symbol in the document:
 	 * var placedCircle = new PlacedSymbol(circleSymbol);
+	 * 
+	 * // Move the placed symbol to {x: 150, y: 150}:
 	 * placedCircle.position = new Point(150, 150);
-	 * </pre>
+	 * 
+	 * @class Symbols allow you to place multiple instances of an item in your
+	 *        project. This can save memory, since all instances of a symbol
+	 *        simply refer to the original item and it can speed up moving
+	 *        around complex objects, since internal properties such as segment
+	 *        lists and gradient positions don't need to be updated with every
+	 *        transformation.
 	 */
 	initialize: function(item) {
 		this.project = paper.project;

src/text/CharacterStyle.js

@@ -30,13 +30,15 @@ var CharacterStyle = this.CharacterStyle = PathStyle.extend({
 	 * @class The CharacterStyle object represents the character style of a text
 	 * item ({@link TextItem#characterStyle})
 	 * 
-	 * Sample code:
+	 * Example:
-	 * <pre>
+	 * <code>
 	 * var text = new PointText(new Point(50, 50));
-	 * text.fillColor = 'black';
 	 * text.content = 'Hello world.';
-	 * text.characterStyle.fontSize = 50;
+	 * text.characterStyle = {
-	 * </pre>
+	 * 	fontSize: 50,
+	 * 	fillColor: 'black',
+	 * };
+	 * </code>
 	 * 
 	 * @extends PathStyle
 	 */

src/text/PointText.js

@@ -23,21 +23,18 @@ var PointText = this.PointText = TextItem.extend({
 	 * Creates a point text item
 	 * 
 	 * @param {Point} point the position where the text will start
-	 * 
 	 * @constructs PointText
+	 * 
+	 * @example
+	 * var text = new PointText(new Point(50, 100));
+	 * text.paragraphStyle.justification = 'center';
+	 * text.characterStyle.fillColor = 'black';
+	 * text.content = 'The contents of the point text';
 	 *
 	 * @class A PointText item represents a piece of typography in your Paper.js
 	 * project which starts from a certain point and extends by the amount of
 	 * characters contained in it.
 	 * 
-	 * Sample code:
-	 * <pre>
-	 * var text = new PointText(new Point(50, 100));
-	 * text.paragraphStyle.justification = 'center';
-	 * text.content = 'The contents of the point text';
-	 * text.fillColor = 'black';
-	 * </pre>
-	 * 
 	 * @extends TextItem
 	 * @extends Item
 	 */

src/tool/Tool.js

@@ -46,12 +46,13 @@ var Tool = this.Tool = Base.extend({
 	 * function onMouseDown(event) {
 	 * 	// Create a new path every time the mouse is clicked
 	 * 	path = new Path();
+	 * 	path.add(event.point);
 	 * 	path.strokeColor = 'black';
 	 * }
 	 * 
 	 * function onMouseDrag(event) {
 	 * 	// Add a point to the path every time the mouse is dragged
-	 * 	path.lineTo(event.point);
+	 * 	path.add(event.point);
 	 * }
 	 * </pre>
 	 */
@@ -134,15 +135,18 @@ var Tool = this.Tool = Base.extend({
 	 * function receives a {@link ToolEvent} object which contains information
 	 * about the mouse event.
 	 * 
-	 * @example
-	 * function onMouseDown(event) {
-	 * 	// the position of the mouse in project coordinates:
-	 * 	console.log(event.point);
-	 * }
-	 * 
 	 * @name Tool#onMouseDown
 	 * @property
 	 * @type function
+	 * 
+	 * @example
+	 * // Creating circle shaped paths where the user presses the mouse button:
+	 * function onMouseDown(event) {
+	 * 	// Create a new circle shaped path with a radius of 10
+	 * 	// at the position of the mouse (event.point):
+	 * 	var path = new Path.Circle(event.point, 10);
+	 * 	path.fillColor = 'black';
+	 * }
 	 */
 
 	/**
@@ -153,30 +157,44 @@ var Tool = this.Tool = Base.extend({
 	 * This function can also be called periodically while the mouse doesn't
 	 * move by setting the {@link #eventInterval}
 	 * 
-	 * @example
-	 * function onMouseDrag(event) {
-	 * 	// the position of the mouse in project coordinates
-	 * 	console.log(event.point);
-	 * }
-	 * 
 	 * @name Tool#onMouseDrag
 	 * @property
 	 * @type function
+	 * 
+	 * @example
+	 * // Draw a line by adding a segment to a path on every mouse drag event:
+	 * 
+	 * // Create an empty path:
+	 * var path = new Path();
+	 * path.strokeColor = 'black';
+	 * 
+	 * function onMouseDrag(event) {
+	 * 	// Add a segment to the path at the position of the mouse:
+	 * 	path.add(event.point);
+	 * }
 	 */
 
 	/**
-	 * The function to be called when the tool is selected and the mouse moves
+	 * The function to be called the mouse moves within the project view. The
-	 * within the document. The function receives a {@link ToolEvent} object
+	 * function receives a {@link ToolEvent} object which contains information
-	 * which contains information about the mouse event.
+	 * about the mouse event.
 	 * 
-	 * @example
-	 * function onMouseMove(event) {
-	 * 	// the position of the mouse in project coordinates
-	 * 	console.log(event.point);
-	 * }
 	 * @name Tool#onMouseMove
 	 * @property
 	 * @type function
+	 * 
+	 * @example
+	 * // Moving a path to the position of the mouse:
+	 *
+	 * // Create a circle shaped path with a radius of 10 at {x: 0, y: 0}:
+	 * var path = new Path.Circle([0, 0], 10);
+	 * path.fillColor = 'black';
+	 * 
+	 * function onMouseMove(event) {
+	 * 	// Whenever the user moves the mouse, move the path
+	 * 	// to that position:
+	 * 	path.position = event.point;
+	 * }
 	 */
 
 	/**
@@ -184,14 +202,18 @@ var Tool = this.Tool = Base.extend({
 	 * receives a {@link ToolEvent} object which contains information about the
 	 * mouse event.
 	 * 
-	 * @example
-	 * function onMouseUp(event) {
-	 * 	// the position of the mouse in project coordinates
-	 * 	console.log(event.point);
-	 * }
 	 * @name Tool#onMouseUp
 	 * @property
 	 * @type function
+	 * 
+	 * @example
+	 * // Creating circle shaped paths where the user releases the mouse:
+	 * function onMouseUp(event) {
+	 * 	// Create a new circle shaped path with a radius of 10
+	 * 	// at the position of the mouse (event.point):
+	 * 	var path = new Path.Circle(event.point, 10);
+	 * 	path.fillColor = 'black';
+	 * }
 	 */
 
 	/**
@@ -205,15 +227,26 @@ var Tool = this.Tool = Base.extend({
 	 * window from scrolling, when you need the user to interact with arrow
 	 * keys.
 	 * 
-	 * @example
-	 * function onKeyDown(event) {
-	 * 	if(event.key == 'space') {
-	 * 		console.log('The spacebar was pressed!');
-	 * 	}
-	 * }
 	 * @name Tool#onKeyDown
 	 * @property
 	 * @type Function
+	 * 
+	 * @example
+	 * // Scaling a path whenever the user presses the space bar:
+	 * 
+	 * // Create a circle shaped path:
+	 * var path = new Path.Circle(new Point(50, 50), 30);
+	 * path.fillColor = 'red';
+	 * 
+	 * function onKeyDown(event) {
+	 * 	if(event.key == 'space') {
+	 * 		// Scale the path by 110%:
+	 * 		path.scale(1.1);
+	 * 
+	 * 		// Prevent the key event from bubbling
+	 * 		return false;
+	 * 	}
+	 * }
 	 */
 
 	/**
@@ -224,6 +257,10 @@ var Tool = this.Tool = Base.extend({
 	 * prevented from bubbling up. This can be used for example to stop the
 	 * window from scrolling, when you need the user to interact with arrow
 	 * keys.
+	 *
+	 * @name Tool#onKeyUp
+	 * @property
+	 * @type Function
 	 * 
 	 * @example
 	 * function onKeyUp(event) {
@@ -231,10 +268,6 @@ var Tool = this.Tool = Base.extend({
 	 * 		console.log('The spacebar was released!');
 	 * 	}
 	 * }
-	 *
-	 * @name Tool#onKeyUp
-	 * @property
-	 * @type Function
 	 */
 
 	updateEvent: function(type, pt, minDistance, maxDistance, start,

src/ui/Key.js

@@ -14,6 +14,10 @@
  * All rights reserved.
  */
 
+/**
+ * @namespace
+ * @name Key
+ */
 var Key = this.Key = new function() {
 	// TODO: make sure the keys are called the same as in Scriptographer
 	// Missing: tab, cancel, clear, page-down, page-up, comma, minus, period,
@@ -72,7 +76,7 @@ var Key = this.Key = new function() {
 			// Call the onKeyDown or onKeyUp handler if present
 			// When the handler function returns false, prevent the
 			// default behaviour of the key event:
-			// PORT: Add to Scriptographer
+			// PORT: Add to Sg
 			var keyEvent = new KeyEvent(down, key, character, event);
 			if (tool[handler](keyEvent) === false)
 				keyEvent.preventDefault();
@@ -118,7 +122,7 @@ var Key = this.Key = new function() {
 			var code = event.which || event.keyCode,
 				key = keys[code], name;
 			if (key && modifiers[name = Base.camelize(key)] !== undefined) {
-				modifiers[name] = false
+				modifiers[name] = false;
 			} else if (charCodeMap[code] != null) {
 				handleKey(false, code, charCodeMap[code], event);
 				delete charCodeMap[code];
@@ -127,8 +131,30 @@ var Key = this.Key = new function() {
 	});
 
 	return {
+		/** @lends Key */
+
 		modifiers: modifiers,
 
+		/**
+		 * Checks whether the specified key is pressed.
+		 * 
+		 * @param {String} key One of: 'backspace', 'enter', 'shift', 'control',
+		 * 'option', 'pause', 'caps-lock', 'escape', 'space', 'end', 'home',
+		 * 'left', 'up', 'right', 'down', 'delete', 'command'
+		 * @return {Boolean} {@true if the key is pressed}
+		 * 
+		 * @example
+		 * // Whenever the user clicks, create a circle shaped path. If the
+		 * // shift key is down, fill it with red, otherwise fill it with blue:
+		 * function onMouseDown(event) {
+		 * 	var path = new Path.Circle(event.point, 10);
+		 * 	if(Key.isDown('shift')) {
+		 * 		path.fillColor = 'red';
+		 * 	} else {
+		 * 		path.fillColor = 'blue';
+		 * 	}
+		 * }
+		 */
 		isDown: function(key) {
 			return !!keyMap[key];
 		}