Clean up and separate PaperScript documetation from JavaScript related classes. Work in progress.

src/core/PaperScope.js

@@ -17,12 +17,26 @@
 /**
  * @name PaperScope
  *
- * @class Internal PaperScope class that handles all the fields available on the
+ * @class The {@code PaperScope} class represents the scope associated with a
- * global paper object, which simply is a pointer to the currently active scope.
+ * Paper context. When working with PaperScript, these scopes are automatically
- *
+ * created and their fields and methods become part of the global scope. When
- * @private
+ * working with normal JavaScript files, {@code PaperScope} objects need to be
+ * manually created and handled.
+ * The global {@link _global_#paper} object is simply a reference to the
+ * currently active {@code PaperScope}.
  */
-var PaperScope = this.PaperScope = Base.extend(/** @scope _global_ */{
+var PaperScope = this.PaperScope = Base.extend(/** @lends PaperScope# */{
+	initialize: function(id) {
+		this.project = null;
+		this.projects = [];
+		this.view = null;
+		this.views = [];
+		this.tool = null;
+		this.tools = [];
+		this.id = id;
+		PaperScope._scopes[id] = this;
+	},
+
 	/**
 	 * The version of Paper.js, as a float number.
 	 *
@@ -30,109 +44,41 @@ var PaperScope = this.PaperScope = Base.extend(/** @scope _global_ */{
 	 */
 	version: VERSION,
 
-	initialize: function(id) {
+	/**
-		/** @lends _global_# */
+	 * The currently active project.
+	 * @name PaperScope#project
+	 * @type Project
+	 */
 
-		/**
+	/**
-		 * The currently active project.
+	 * The list of all open projects within the current Paper.js context.
-		 * @type Project
+	 * @name PaperScope#projects
-		 */
+	 * @type Project[]
-		this.project = null;
+	 */
 
-		/**
+	/**
-		 * The list of all open projects within the current Paper.js context.
+	 * The active view of the active project.
-		 * @type Project[]
+	 * @name PaperScope#view
-		 */
+	 * @type View
-		this.projects = [];
+	 */
 
-		/**
+	/**
-		 * The active view of the active project.
+	 * The list of view of the active project.
-		 * @type View
+	 * @name PaperScope#views
-		 */
+	 * @type View[]
-		this.view = null;
+	 */
 
-		/**
+	/**
-		 * The active view of the active project.
+	 * The reference to the active tool.
-		 * @type View
+	 * @name PaperScope#tool
-		 */
+	 * @type Tool
-		this.views = [];
+	 */
 
-		/**
+	/**
-		 * The reference to the tool object.
+	 * The list of available tools.
-		 * @type Tool
+	 * @name PaperScope#tools
-		 */
+	 * @type Tool[]
-		this.tool = null;
+	 */
-		this.tools = [];
-		this.id = id;
-		PaperScope._scopes[id] = this;
-
-		// DOCS: should the different event handlers be in here?
-		/**
-		 * {@grouptitle View Event Handlers}
-		 * A reference to the {@link View#onFrame} handler function.
-		 *
-		 * @name onFrame
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * A reference to the {@link View#onResize} handler function.
-		 *
-		 * @name onResize
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * {@grouptitle Mouse Event Handlers}
-		 * A reference to the {@link Tool#onMouseDown} handler function.
-		 * @name onMouseDown
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * A reference to the {@link Tool#onMouseDrag} handler function.
-		 *
-		 * @name onMouseDrag
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * A reference to the {@link Tool#onMouseMove} handler function.
-		 *
-		 * @name onMouseMove
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * A reference to the {@link Tool#onMouseUp} handler function.
-		 *
-		 * @name onMouseUp
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * {@grouptitle Keyboard Event Handlers}
-		 * A reference to the {@link Tool#onKeyDown} handler function.
-		 *
-		 * @name onKeyDown
-		 * @property
-		 * @type Function
-		 */
-
-		/**
-		 * A reference to the {@link Tool#onKeyUp} handler function.
-		 *
-		 * @name onKeyUp
-		 * @property
-		 * @type Function
-		 */
-	},
 
 	evaluate: function(code) {
 		var res = PaperScript.evaluate(code, this);
@@ -165,8 +111,6 @@ var PaperScope = this.PaperScope = Base.extend(/** @scope _global_ */{
 	 *
 	 * @example
 	 * paper.install(window);
-	 *
-	 * @ignore
 	 */
 	install: function(scope) {
 		// Use scope as side-car (= 'this' inside iterator), and have it
@@ -201,7 +145,7 @@ var PaperScope = this.PaperScope = Base.extend(/** @scope _global_ */{
 		}
 	},
 
-	statics: {
+	statics: /** @lends PaperScope */{
 		_scopes: {},
 
 		/**
@@ -209,7 +153,6 @@ var PaperScope = this.PaperScope = Base.extend(/** @scope _global_ */{
 		 * the passed canvas element.
 		 *
 		 * @param id
-		 * @ignore
 		 */
 		get: function(id) {
 			// If a script tag is passed, get the id from it.
@@ -219,10 +162,10 @@ var PaperScope = this.PaperScope = Base.extend(/** @scope _global_ */{
 		},
 
 		/**
-		 * A way to iterate over all active scopes without accessing _scopes
+		 * Iterates over all active scopes and calls the passed iterator
+		 * function for each of them.
 		 *
-		 * @param iter
+		 * @param iter the iterator function.
-		 * @ignore
 		 */
 		each: function(iter) {
 			Base.each(this._scopes, iter);

src/core/PaperScript.js

@@ -14,6 +14,10 @@
  * All rights reserved.
  */
 
+/**
+ * @name PaperScript
+ * @namespace
+ */
 var PaperScript = this.PaperScript = new function() {
 //#include "../../lib/parse-js-min.js"
 
@@ -84,6 +88,14 @@ var PaperScript = this.PaperScript = new function() {
 		}
 	}
 
+	/**
+	 * Compiles PaperScript code into JavaScript code.
+	 *
+	 * @name PaperScript.compile
+	 * @function
+	 * @param {String} code The PaperScript code.
+	 * @return {String} The compiled PaperScript as JavaScript code.
+	 */
 	function compile(code) {
 		// Use parse-js to translate the code into a AST structure which is then
 		// walked and parsed for operators to overload. The resulting AST is
@@ -130,6 +142,16 @@ var PaperScript = this.PaperScript = new function() {
 		});
 	}
 
+	/**
+	 * Evaluates parsed PaperScript code in the passed scope. Also handles
+	 * canvas setup, tool creation and handlers automatically.
+	 *
+	 * @name PaperScript.evaluate
+	 * @function
+	 * @param {String} code The compiled PaperScript code.
+	 * @param {PaperScript} scope The scope in which the code is executed.
+	 * @return {Object} The result of the code evaluation.
+	 */
 	function evaluate(code, scope) {
 //#ifdef BROWSER
 		// See if it's a script tag or a string

src/paper.js

@@ -44,10 +44,94 @@
  */
 
 /**
- * The global PaperScope object
+ * @name _global_
- * @name paper
+ *
- * @ignore
+ * @class In a PaperScript context, the global scope is populated with all
+ * fields of the currently active {@link PaperScope} object. In a JavaScript
+ * context, it only contains the {@link #paper} reference to the currently
+ * active {@link PaperScope} object, which also exposes all Paper classes.
  */
+
+/**
+ * {@grouptitle PaperScript Global Properties}
+ *
+ * @borrows PaperScope#version as _global_#version
+ */
+
+/**
+ * A reference to the currently active {@link PaperScope} object.
+ *
+ * @name _global_#paper
+ * @property
+ * @type PaperScope
+ */
+
+/**
+ * {@grouptitle PaperScript View Event Handlers}
+ * A reference to the {@link View#onFrame} handler function.
+ *
+ * @name _global_#onFrame
+ * @property
+ * @type Function
+ */
+
+/**
+ * A reference to the {@link View#onResize} handler function.
+ *
+ * @name _global_#onResize
+ * @property
+ * @type Function
+ */
+
+/**
+ * {@grouptitle PaperScript Mouse Event Handlers}
+ * A reference to the {@link Tool#onMouseDown} handler function.
+ * @name _global_#onMouseDown
+ * @property
+ * @type Function
+ */
+
+/**
+ * A reference to the {@link Tool#onMouseDrag} handler function.
+ *
+ * @name _global_#onMouseDrag
+ * @property
+ * @type Function
+ */
+
+/**
+ * A reference to the {@link Tool#onMouseMove} handler function.
+ *
+ * @name _global_#onMouseMove
+ * @property
+ * @type Function
+ */
+
+/**
+ * A reference to the {@link Tool#onMouseUp} handler function.
+ *
+ * @name _global_#onMouseUp
+ * @property
+ * @type Function
+ */
+
+/**
+ * {@grouptitle PaperScript Keyboard Event Handlers}
+ * A reference to the {@link Tool#onKeyDown} handler function.
+ *
+ * @name _global_#onKeyDown
+ * @property
+ * @type Function
+ */
+
+/**
+ * A reference to the {@link Tool#onKeyUp} handler function.
+ *
+ * @name _global_#onKeyUp
+ * @property
+ * @type Function
+ */
+
 var paper = new function() {
 // Inline Bootstrap core (the Base class) inside the paper scope first:
 //#include "../lib/bootstrap.js"

src/project/Project.js

@@ -29,10 +29,10 @@
  * SVG and PDF.
  *
  * The currently active project can be accessed through the global
- * {@see _global_#project} variable.
+ * {@see PaperScope#project} variable.
  *
  * An array of all open projects is accessible through the global
- * {@see _global_#projects} variable.
+ * {@see PaperScope#projects} variable.
  */
 var Project = this.Project = Base.extend(/** @lends Project# */{
 	// TODO: Add arguments to define pages
@@ -40,7 +40,7 @@ var Project = this.Project = Base.extend(/** @lends Project# */{
 	 * Creates a Paper.js project.
 	 *
 	 * When working with PaperScript, a project is automatically created for us
-	 * and the global {@see _global_#project} variable points to it.
+	 * and the global {@see PaperScope#project} variable points to it.
 	 */
 	initialize: function() {
 		// Store reference to the currently active global paper scope:
@@ -111,7 +111,7 @@ var Project = this.Project = Base.extend(/** @lends Project# */{
 	},
 
 	/**
-	 * Removes this project from the global {@see _global_#projects} list.
+	 * Removes this project from the global {@see PaperScope#projects} list.
 	 */
 	remove: function() {
 		if (this._scope) {

src/style/Style.js

@@ -15,8 +15,12 @@
  */
 
 /**
- * Internal base-class for all style objects, e.g. PathStyle, CharacterStyle,
+ * @name Style
- * PargraphStyle.
+ *
+ * @class Internal base-class for all style objects, e.g. PathStyle,
+ * CharacterStyle, PargraphStyle.
+ *
+ * @private
  */
 var Style = Item.extend({
 	initialize: function(style) {