Added comments to ImportSVG.js

src/svg/ImportSVG.js

@@ -1,33 +1,62 @@
+/*
+* Paper.js
+*
+* This file is part of Paper.js, a JavaScript Vector Graphics Library,
+* based on Scriptographer.org and designed to be largely API compatible.
+* http://paperjs.org/
+* http://scriptographer.org/
+*
+* Copyright (c) 2011, Juerg Lehni & Jonathan Puckey
+* http://lehni.org/ & http://jonathanpuckey.com/
+*
+* Distributed under the MIT license. See LICENSE file for details.
+*
+* All rights reserved.
+*
+*
+*
+* This class and all methods therein designed by Stetson-Team-Alpha
+*/
+
 /**
- *  Imports svg into items with groups
+ * @name ImportSVG
- *  Stetson Alpha - Paper.js
+ *
+ * @class The ImportSVG object represents an object created using the SVG Canvas * that will be converted into a Paper.js object. The SVG object is imported     * into Paper.js by converting it into items within groups.
  *
  */
 
-var ImportSVG = this.ImportSVG = Base.extend({
+var ImportSVG = this.ImportSVG = Base.extend(/** @Lends ImportSVG# */{
+
 	/**
-	 * Takes the svg dom obj and parses the data
+	 * Creates a Paper.js object using data parsed from the selected SVG
-	 * to create a layer with groups (if needed) with
+	 * Document Object Model (DOM). The SVG object is imported, than a layer
-	 * items inside. Should support nested groups.
+	 * is created (with groups for the items if needed).
 	 *
-	 * takes in a svg object (xml dom)
+	 * Supports nested groups
-	 * returns Paper.js Layer
+	 *
+	 * @param {SVG DOM} svg An SVG DOM object with parameters
+	 * @return {Layer} A Paper.js layer
 	 */
+
 	importSVG: function(svg)
 	{
-		var layer = new Layer();
+	var layer = new Layer();
-		groups = this.importGroup(svg);
+	groups = this.importGroup(svg);
-		layer.addChild(groups);
+	layer.addChild(groups);
 
-		return layer;
+	return layer;
 	},
 	
 	/**
-	 * Creates a Paper.js Group by parsing
+	 * Creates a Paper.js group by parsing a specific GNode of the imported
-	 * a specific svg g node
+	 * SVG DOM
+	 * 
+	 * @name ImportSVG#importGroup
+	 * @function
+	 * @param {XML DOM} svg  A node passed in by the imported SVG
+	 * @return {Group} group A Paper.js group
+	 *
 	 *
-	 * takes in a svg object (xml dom)
-	 * returns Paper.js Group
 	 */
 	importGroup: function(svg)
 	{
@@ -47,11 +76,13 @@ var ImportSVG = this.ImportSVG = Base.extend({
 
 	/**
 	 * Creates a Paper.js Path by parsing
-	 * a specific svg node (rect, path, circle, polygon, etc)
+	 * a specific SVG node (rectangle, path, circle, polygon, etc.)
-	 * and creating the right path object based on the svg type.
+	 * and creating the right Path object based on the SVG type.
 	 *
-	 * takes in a svg object (xml dom)
+	 * @name ImportSVG#importPath
-	 * returns Paper.js Item
+	 * @function
+	 * @param {XML DOM} svg An SVG object
+	 * @return {Item} item A Paper.js item
 	 */
 	importPath: function(svg)
 	{
@@ -79,10 +110,13 @@ var ImportSVG = this.ImportSVG = Base.extend({
 	},
 
 	/**
-	 * Creates a Path.Circle Paper.js item
+	 * Creates a Path.Circle item in Paper.js using an imported Circle from
+	 * SVG
 	 *
-	 * takes a svg circle node (xml dom)
+	 * @name ImportSVG#importCircle
-	 * returns Paper.js Path.Circle item
+	 * @function
+	 * @param {XML DOM} svgCircle An SVG circle node
+	 * @return {Path.Circle} circle A Path.Circle item for Paper.js
 	 */
 	_importCircle: function(svgCircle)
 	{
@@ -96,10 +130,12 @@ var ImportSVG = this.ImportSVG = Base.extend({
 	},
 
 	/**
-	 * Creates a Path.Oval Paper.js item
+	 * Creates a Path.Oval item in Paper.js using an imported Oval from SVG
 	 *
-	 * takes a svg ellipse node (xml dom)
+	 * @name ImportSVG#importOval
-	 * returns Paper.js Path.Oval item
+	 * @function
+	 * @param {XML DOM} svgOval An SVG ellipse node
+	 * @return {Path.Oval} oval A Path.Oval item for Paper.js
 	 */
 	_importOval: function(svgOval)
 	{
@@ -120,13 +156,23 @@ var ImportSVG = this.ImportSVG = Base.extend({
 	},
 
 	/**
-	 * Creates a "rectangle" Paper.js item
+	 * Creates a Path.Rectangle item from an imported SVG rectangle
 	 *
-	 * takes a svg rect node (xml dom)
+	 * @name ImportSVG#importRectangle
-	 * returns either a
+	 * @function
-	 *   - Path.Rectangle item
+	 * @param {XML DOM} svgRectangle An SVG rectangle node
-	 *   - Path.RoundRectangle item (if the rectangle has rounded corners)
+	 * @return {Path.Rectangle} rectangle A Path.Rectangle item for Paper.js
 	 */
+	 /**
+	 * Creates a Path.RoundRectangle item from an imported SVG rectangle
+	 * with rounded corners
+	 *
+	 * @name ImportSVG#importRectangle
+	 * @function
+	 * @param {XML DOM} svgRectangle An SVG rectangle node with rounded
+	 * corners
+	 * @return {Path.RoundRectangle} rectangle A Path.Rectangle item for
+	 * Paper.js
 	_importRectangle: function(svgRectangle)
 	{
 		var x			= svgRectangle.x.baseVal.value || 0;
@@ -151,10 +197,12 @@ var ImportSVG = this.ImportSVG = Base.extend({
 	},
 
 	/**
-	 * Creates a Path.Line Paper.js item
+	 * Creates a Path.Line item in Paper.js from an imported SVG line
 	 *
-	 * takes a svg line node (xml dom)
+	 * @name ImportSVG#importLine
-	 * returns a Path.Line item
+	 * @function
+	 * @param {XML DOM} svgLine An SVG line node
+	 * @return {Path.Line} line A Path.Line item for Paper.js
 	 */
 	_importLine: function(svgLine)
 	{
@@ -171,10 +219,12 @@ var ImportSVG = this.ImportSVG = Base.extend({
 	},
 
 	/**
-	 * Creates a PointText Paper.js item
+	 * Creates a PointText item in Paper.js from an imported SVG text node
 	 *
-	 * takes a svg text node (xml dom)
+	 * @name ImportSVG#importText
-	 * returns a PointText item
+	 * @function
+	 * @param {XML DOM} svgText An SVG text node
+	 * @return {Path.Text} text A PointText item for Paper.js
 	 */
 	_importText: function(svgText)
 	{