From 43cc8e45b2501d8b22998db91ad1ba4a8e4dda28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrg=20Lehni?= Date: Mon, 25 Jul 2011 00:25:23 +0100 Subject: [PATCH] Clean up and separate PaperScript documetation from JavaScript related classes. Work in progress. --- src/core/PaperScope.js | 163 +++++++++++++--------------------------- src/core/PaperScript.js | 22 ++++++ src/paper.js | 90 +++++++++++++++++++++- src/project/Project.js | 8 +- src/style/Style.js | 8 +- 5 files changed, 172 insertions(+), 119 deletions(-) diff --git a/src/core/PaperScope.js b/src/core/PaperScope.js index b6b5d788..4b595d35 100644 --- a/src/core/PaperScope.js +++ b/src/core/PaperScope.js @@ -17,12 +17,26 @@ /** * @name PaperScope * - * @class Internal PaperScope class that handles all the fields available on the - * global paper object, which simply is a pointer to the currently active scope. - * - * @private + * @class The {@code PaperScope} class represents the scope associated with a + * Paper context. When working with PaperScript, these scopes are automatically + * created and their fields and methods become part of the global scope. When + * 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. - * @type Project - */ - this.project = null; + /** + * The list of all open projects within the current Paper.js context. + * @name PaperScope#projects + * @type Project[] + */ - /** - * The list of all open projects within the current Paper.js context. - * @type Project[] - */ - this.projects = []; + /** + * The active view of the active project. + * @name PaperScope#view + * @type View + */ - /** - * The active view of the active project. - * @type View - */ - this.view = null; + /** + * The list of view of the active project. + * @name PaperScope#views + * @type View[] + */ - /** - * The active view of the active project. - * @type View - */ - this.views = []; + /** + * The reference to the active tool. + * @name PaperScope#tool + * @type Tool + */ - /** - * The reference to the tool object. - * @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 - */ - }, + /** + * The list of available tools. + * @name PaperScope#tools + * @type Tool[] + */ 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 - * @ignore + * @param iter the iterator function. */ each: function(iter) { Base.each(this._scopes, iter); diff --git a/src/core/PaperScript.js b/src/core/PaperScript.js index 974baa44..26d72504 100644 --- a/src/core/PaperScript.js +++ b/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 diff --git a/src/paper.js b/src/paper.js index cbfa2d68..ee31cb03 100644 --- a/src/paper.js +++ b/src/paper.js @@ -44,10 +44,94 @@ */ /** - * The global PaperScope object - * @name paper - * @ignore + * @name _global_ + * + * @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" diff --git a/src/project/Project.js b/src/project/Project.js index 27908b5d..cecff275 100644 --- a/src/project/Project.js +++ b/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) { diff --git a/src/style/Style.js b/src/style/Style.js index cf852576..9dd61960 100644 --- a/src/style/Style.js +++ b/src/style/Style.js @@ -15,8 +15,12 @@ */ /** - * Internal base-class for all style objects, e.g. PathStyle, CharacterStyle, - * PargraphStyle. + * @name Style + * + * @class Internal base-class for all style objects, e.g. PathStyle, + * CharacterStyle, PargraphStyle. + * + * @private */ var Style = Item.extend({ initialize: function(style) {