From 5bd935be75097e8542f0dbe8b16cf2661afbc929 Mon Sep 17 00:00:00 2001
From: Jonathan Puckey <me@jonathanpuckey.com>
Date: Mon, 23 May 2011 18:28:48 +0200
Subject: [PATCH] Symbol documentation & move Symbol#clone below
 Symbol#setDefinition.

---
 src/project/Symbol.js | 56 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/src/project/Symbol.js b/src/project/Symbol.js
index 779b99dd..889d44b4 100644
--- a/src/project/Symbol.js
+++ b/src/project/Symbol.js
@@ -15,20 +15,59 @@
  */
 
 var Symbol = this.Symbol = Base.extend({
+	/** @lends Symbol# */
+
 	beans: true,
 
+	/**
+	 * Creates a Symbol item.
+	 * 
+	 * Sample code:
+	 * @example
+	 * var circlePath = new Path.Circle(new Point(100, 100), 50);
+	 * circlePath.fillColor = 'red';
+	 * 
+	 * var circleSymbol = new Symbol(circlePath);
+	 * circleSymbol.name = 'Circle';
+	 * 
+	 * // The original item is still contained in the document:
+	 * circlePath.remove();
+	 * 
+	 * // The symbol can now also be accessed
+	 * // through project.symbols:
+	 * console.log(project.symbols['Circle']);
+	 * 
+	 * // To place instances of the symbol in the document:
+	 * var placedCircle = new PlacedSymbol(circleSymbol);
+	 * placedCircle.position = new Point(150, 150);
+	 * 
+	 * @param {Item} item the source item which is copied as the definition of
+	 *               the symbol
+	 *
+	 * @name Symbol
+	 * @constructor
+	 * 
+	 * @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;
 		this.project.symbols.push(this);
 		this.setDefinition(item);
 	},
 
-	clone: function() {
-	 	return new Symbol(this._definition.clone());
-	},
-
 	// TODO: remove()
 
+	/**
+	 * The symbol definition.
+	 * 
+	 * @type Item
+	 * @bean
+	 */
 	getDefinition: function() {
 		return this._definition;
 	},
@@ -40,5 +79,14 @@ var Symbol = this.Symbol = Base.extend({
 		item._removeFromParent();
 		// Move position to 0, 0. TODO: Why?
 		item.setPosition(new Point());
+	},
+
+	/**
+	 * Returns a copy of the symbol.
+	 * 
+	 * @return {Symbol}
+	 */
+	clone: function() {
+	 	return new Symbol(this._definition.clone());
 	}
 });