Implement Symbol#place(position)

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/project/Symbol.js

@@ -28,20 +28,35 @@ var Symbol = this.Symbol = Base.extend({
 	 * @name Symbol
 	 * @constructor
 	 * 
-	 * @example
+	 * @example {@paperscript split=true height=240}
-	 * var circlePath = new Path.Circle(new Point(100, 100), 50);
+	 * // Placing 100 instances of a symbol:
-	 * circlePath.fillColor = 'red';
+	 * 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);
+	 * // Remove the path:
-	 * 
+	 * path.remove();
-	 * // The original item is still contained in the document:
+     * 
-	 * circlePath.remove();
+	 * // Place 100 instances of the symbol:
-	 * 
+	 * for (var i = 0; i < 100; i++) {
-	 * // Place an instance of the symbol in the document:
+	 *     // Place an instance of the symbol in the project:
-	 * var placedCircle = new PlacedSymbol(circleSymbol);
+	 *     var instance = symbol.place();
-	 * 
+     * 
-	 * // Move the placed symbol to {x: 150, y: 150}:
+	 *     // Move the instance to a random position within the view:
-	 * placedCircle.position = new Point(150, 150);
+	 *     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.
 	 *