Documentation edits.

src/color/Color.js

@@ -306,11 +306,25 @@ var Color = this.Color = Base.extend(new function() {
 	},
 
 	/**
-	 * A value between {@code 0} and {@code 1} that specifies the color's alpha
+	 * The color's alpha value as a number between {@code 0} and {@code 1}. All
-	 * value. All colors of the different subclasses support alpha values.
+	 * colors of the different subclasses support alpha values.
 	 * 
 	 * @type Number
 	 * @bean
+	 * 
+	 * @example {@paperscript}
+	 * // A filled path with a half transparent stroke:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 * 
+	 * // Fill the circle with red and give it a 20pt green stroke:
+	 * circle.style = {
+	 * 	fillColor: 'red',
+	 * 	strokeColor: 'green',
+	 * 	strokeWidth: 20
+	 * };
+	 * 
+	 * // Make the stroke half transparent:
+	 * circle.strokeColor.alpha = 0.5;
 	 */
 	getAlpha: function() {
 		return this._alpha != null ? this._alpha : 1;
@@ -368,7 +382,7 @@ var Color = this.Color = Base.extend(new function() {
 	},
 
 	/**
-	 * @return {String} A css representation of the color.
+	 * @return {String} A css string representation of the color.
 	 */
 	toCssString: function() {
 		if (!this._cssString) {
@@ -398,6 +412,14 @@ var Color = this.Color = Base.extend(new function() {
 	 * @name Color#red
 	 * @property
 	 * @type Number
+	 * 
+	 * @example {@paperscript}
+	 * // Changing the amount of red in a color:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 * circle.fillColor = 'blue';
+	 * 
+	 * // Blue + red = purple:
+	 * circle.fillColor.red = 1;
 	 */
 
 	/**
@@ -407,6 +429,16 @@ var Color = this.Color = Base.extend(new function() {
 	 * @name Color#green
 	 * @property
 	 * @type Number
+	 * 
+	 * @example {@paperscript}
+	 * // Changing the amount of green in a color:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 * 
+	 * // First we set the fill color to red:
+	 * circle.fillColor = 'red';
+	 * 
+	 * // Red + green = yellow:
+	 * circle.fillColor.green = 1;
 	 */
 
 	/**
@@ -416,6 +448,16 @@ var Color = this.Color = Base.extend(new function() {
 	 * @name Color#blue
 	 * @property
 	 * @type Number
+	 * 
+	 * @example {@paperscript}
+	 * // Changing the amount of blue in a color:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 * 
+	 * // First we set the fill color to red:
+	 * circle.fillColor = 'red';
+	 * 
+	 * // Red + blue = purple:
+	 * circle.fillColor.blue = 1;
 	 */
 
 	/**
@@ -438,6 +480,24 @@ var Color = this.Color = Base.extend(new function() {
 	 * @name Color#hue
 	 * @property
 	 * @type Number
+	 * 
+	 * @example {@paperscript}
+	 * // Changing the hue of a color:
+	 * var circle = new Path.Circle(new Point(80, 50), 30);
+	 * circle.fillColor = 'red';
+	 * circle.fillColor.hue += 30;
+	 * 
+	 * @example {@paperscript}
+	 * // Hue cycling:
+	 * 
+	 * // Create a rectangle shaped path, using the dimensions
+	 * // of the view:
+	 * var path = new Path.Rectangle(view.bounds);
+	 * path.fillColor = 'red';
+	 * 
+	 * function onFrame(event) {
+	 * 	path.fillColor.hue += 0.5;
+	 * }
 	 */
 
 	/**

src/item/Item.js

@@ -1037,9 +1037,10 @@ var Item = this.Item = Base.extend({
 	/**
 	 * The miter limit of the stroke.
 	 * When two line segments meet at a sharp angle and miter joins have been
-	 * specified for {@link #strokeJoin}, it is possible for the miter to extend
+	 * specified for {@link Item#strokeJoin}, it is possible for the miter to
-	 * far beyond the {@link #strokeWidth} of the path. The miterLimit imposes a
+	 * extend far beyond the {@link Item#strokeWidth} of the path. The
-	 * limit on the ratio of the miter length to the {@link #strokeWidth}.
+	 * miterLimit imposes a limit on the ratio of the miter length to the
+	 * {@link Item#strokeWidth}.
 	 * 
 	 * @property
 	 * @default 10
@@ -1164,12 +1165,17 @@ var Item = this.Item = Base.extend({
 	 * // Rotating an item around a specific point:
 	 * 
 	 * // Create a rectangle shaped path with its top left
-	 * // point at {x: 180, y: 125} and a size of {width: 20, height: 20}:
+	 * // point at {x: 175, y: 50} and a size of {width: 100, height: 100}:
-	 * var topLeft = new Point(180, 125);
+	 * var topLeft = new Point(175, 50);
-	 * var size = new Size(20, 20);
+	 * var size = new Size(100, 100);
 	 * var path = new Path.Rectangle(topLeft, size);
 	 * path.fillColor = 'black';
 	 * 
+	 * // Draw a circle shaped path in the center of the view,
+	 * // to show the rotation point:
+	 * var circle = new Path.Circle(view.center, 5);
+	 * circle.fillColor = 'white';
+	 * 
 	 * // Each frame rotate the path 3 degrees around the center point
 	 * // of the view:
 	 * function onFrame(event) {

src/path/CompoundPath.js

@@ -23,8 +23,8 @@ var CompoundPath = this.CompoundPath = PathItem.extend({
 	 * @constructs CompoundPath
 	 * @param {Array} [paths] the paths to place within the compound path.
 	 * 
-	 * @example
+	 * @example {@paperscript}
-	 * // Create a donut shaped compound path:
+	 * // Create a circle shaped path with a hole in it:
 	 * 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]);

src/path/Path.js

@@ -167,7 +167,7 @@ var Path = this.Path = PathItem.extend({
 	 * @type Boolean
 	 * @bean
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * var myPath = new Path();
 	 * myPath.strokeColor = 'black';
 	 * myPath.add(new Point(40, 90));

src/tool/Tool.js

@@ -139,7 +139,7 @@ var Tool = this.Tool = Base.extend({
 	 * @property
 	 * @type function
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * // 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
@@ -161,7 +161,7 @@ var Tool = this.Tool = Base.extend({
 	 * @property
 	 * @type function
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * // Draw a line by adding a segment to a path on every mouse drag event:
 	 * 
 	 * // Create an empty path:
@@ -183,7 +183,7 @@ var Tool = this.Tool = Base.extend({
 	 * @property
 	 * @type function
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * // Moving a path to the position of the mouse:
 	 *
 	 * // Create a circle shaped path with a radius of 10 at {x: 0, y: 0}:
@@ -206,7 +206,7 @@ var Tool = this.Tool = Base.extend({
 	 * @property
 	 * @type function
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * // Creating circle shaped paths where the user releases the mouse:
 	 * function onMouseUp(event) {
 	 * 	// Create a new circle shaped path with a radius of 10
@@ -231,7 +231,7 @@ var Tool = this.Tool = Base.extend({
 	 * @property
 	 * @type Function
 	 * 
-	 * @example
+	 * @example {@paperscript}
 	 * // Scaling a path whenever the user presses the space bar:
 	 * 
 	 * // Create a circle shaped path: