Merge remote-tracking branch 'origin/master'

src/basic/Point.js

@@ -702,7 +702,7 @@ var Point = this.Point = Base.extend({
 	},
 	
 	/**
-	 * {@grouptitle Vectorial Math Functions}
+	 * {@grouptitle Vector Math Functions}
 	 * Returns the dot product of the point and another point.
 	 * 
 	 * @param {Point} point

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
-	 * value. All colors of the different subclasses support alpha values.
+	 * The color's alpha value as a number between {@code 0} and {@code 1}. All
+	 * 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
-	 * far beyond the {@link #strokeWidth} of the path. The miterLimit imposes a
-	 * limit on the ratio of the miter length to the {@link #strokeWidth}.
+	 * specified for {@link Item#strokeJoin}, it is possible for the miter to
+	 * extend far beyond the {@link Item#strokeWidth} of the path. The
+	 * 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}:
-	 * var topLeft = new Point(180, 125);
-	 * var size = new Size(20, 20);
+	 * // point at {x: 175, y: 50} and a size of {width: 100, height: 100}:
+	 * var topLeft = new Point(175, 50);
+	 * 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/item/PlacedSymbol.js

@@ -27,7 +27,7 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
 	 * symbol or a {@link Matrix} transformation to transform the placed symbol
 	 * with.
 	 * 
-	 * @example {@paperscript split=true}
+	 * @example {@paperscript split=true height=240}
 	 * // Placing 100 instances of a symbol:
 	 * var path = new Path.Star(new Point(0, 0), 6, 5, 13);
 	 * path.style = {
@@ -36,8 +36,10 @@ var PlacedSymbol = this.PlacedSymbol = Item.extend({
 	 * };
      * 
 	 * // Create a symbol from the path:
-	 * // (the original path is removed from the project)
 	 * var symbol = new Symbol(path);
+	 * 
+	 * // Remove the path:
+	 * path.remove();
      * 
 	 * // Place 100 instances of the symbol:
 	 * for (var i = 0; i < 100; i++) {

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
-	 * // Create a donut shaped compound path:
+	 * @example {@paperscript}
+	 * // 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

@@ -166,6 +166,16 @@ var Path = this.Path = PathItem.extend({
 	 * 
 	 * @type Boolean
 	 * @bean
+	 * 
+	 * @example {@paperscript}
+	 * var myPath = new Path();
+	 * myPath.strokeColor = 'black';
+	 * myPath.add(new Point(40, 90));
+	 * myPath.add(new Point(90, 40));
+	 * myPath.add(new Point(140, 90));
+	 * 
+	 * // Close the path:
+	 * myPath.closed = true;
 	 */
 	getClosed: function() {
 		return this._closed;
@@ -597,8 +607,11 @@ var Path = this.Path = PathItem.extend({
 	// PORT: Rename functions and add new isParameter argument in Scriptographer
 	// DOCS: document Path#getLocationAt
 	/**
+	 * {@grouptitle Positions on Paths and Curves}
+	 * 
 	 * @param {Number} offset
 	 * @param {Boolean} [isParameter=false]
+	 * @return CurveLocation
 	 */
 	getLocationAt: function(offset, isParameter) {
 		var curves = this.getCurves(),
@@ -876,7 +889,11 @@ var Path = this.Path = PathItem.extend({
 			}
 		},
 
+		// DOCS: implement @movebefore tag and move the Path#smooth function up
+		// in the documentation.
 		/**
+		 * {@grouptitle Path Smoothing}
+		 * 
 		 * Smooth bezier curves without changing the amount of segments or their
 		 * points, by only smoothing and adjusting their handle points, for both
 		 * open ended and closed paths.

src/project/Symbol.js

@@ -28,20 +28,35 @@ var Symbol = this.Symbol = Base.extend({
 	 * @name Symbol
 	 * @constructor
 	 * 
-	 * @example
-	 * var circlePath = new Path.Circle(new Point(100, 100), 50);
-	 * circlePath.fillColor = 'red';
+	 * @example {@paperscript split=true height=240}
+	 * // Placing 100 instances of a symbol:
+	 * var path = new Path.Star(new Point(0, 0), 6, 5, 13);
+	 * path.style = {
+	 *     fillColor: 'white',
+	 *     strokeColor: 'black'
+	 * };
+     * 
+	 * // Create a symbol from the path:
+	 * var symbol = new Symbol(path);
 	 * 
-	 * var circleSymbol = new Symbol(circlePath);
-	 * 
-	 * // The original item is still contained in the document:
-	 * circlePath.remove();
-	 * 
-	 * // 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);
+	 * // Remove the path:
+	 * path.remove();
+     * 
+	 * // Place 100 instances of the symbol:
+	 * for (var i = 0; i < 100; i++) {
+	 *     // Place an instance of the symbol in the project:
+	 *     var instance = symbol.place();
+     * 
+	 *     // Move the instance to a random position within the view:
+	 *     instance.position = Point.random() * view.size;
+     * 
+	 *     // Rotate the instance by a random amount between
+	 *     // 0 and 360 degrees:
+	 *     instance.rotate(Math.random() * 360);
+     * 
+	 *     // Scale the instance between 0.25 and 1:
+	 *     instance.scale(0.25 + Math.random() * 0.75);
+	 * }
 	 * 
 	 * @class Symbols allow you to place multiple instances of an item in your
 	 *        project. This can save memory, since all instances of a symbol
@@ -86,6 +101,16 @@ var Symbol = this.Symbol = Base.extend({
 		item.setPosition(new Point());
 	},
 
+	/**
+	 * Places in instance of the symbol in the project.
+	 * 
+	 * @param [position] The position of the placed symbol.
+	 * @return {PlacedSymbol}
+	 */
+	place: function(position) {
+		return new PlacedSymbol(this, position);
+	},
+
 	/**
 	 * Returns a copy of the symbol.
 	 * 

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:

test/tests/PlacedSymbol.js

@@ -37,4 +37,30 @@ test('Symbol definition selection', function() {
 	equals(function() {
 		return paper.project.selectedItems.length == 0;
 	}, true);
-});
+});
+
+test('Symbol#place()', function() {
+	var path = new Path.Circle([50, 50], 50);
+	var symbol = new Symbol(path);
+	var placedSymbol = symbol.place();
+	equals(function() {
+		return placedSymbol.parent == paper.project.activeLayer;
+	}, true);
+
+	equals(function() {
+		return placedSymbol.symbol == symbol;
+	}, true);
+
+	equals(function() {
+		return placedSymbol.position.toString();
+	}, '{ x: 0, y: 0 }');
+});
+
+test('Symbol#place(position)', function() {
+	var path = new Path.Circle([50, 50], 50);
+	var symbol = new Symbol(path);
+	var placedSymbol = symbol.place(new Point(100, 100));
+	equals(function() {
+		return placedSymbol.position.toString();
+	}, '{ x: 100, y: 100 }');
+});