Index: openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/gfx/path.js
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/gfx/Attic/path.js,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/gfx/path.js	6 Nov 2006 14:50:07 -0000	1.1
+++ openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/gfx/path.js	25 Dec 2006 16:39:52 -0000	1.2
@@ -15,11 +15,11 @@
 dojo.require("dojo.gfx.shape");
 
 dojo.declare("dojo.gfx.path.Path", dojo.gfx.Shape, {
-	// summary:
-	//		a path shape
-	initializer: function(/* Node */ rawNode){
+	// summary: a generalized path shape
+	
+	initializer: function(rawNode){
 		// summary: a constructor of a path shape object
-		// rawNode: a DOM node to be used by this path object
+		// rawNode: Node: a DOM node to be used by this path object
 		this.shape = dojo.lang.shallowCopy(dojo.gfx.defaultPath, true);
 		this.segments = [];
 		this.absolute = true;
@@ -28,28 +28,32 @@
 	},
 	
 	// mode manipulations
-	setAbsoluteMode: function(/* Boolean||String */ mode){
+	setAbsoluteMode: function(mode){
 		// summary: sets an absolute or relative mode for path points
-		// mode: true/false or "absolute"/"relative" to specify the mode
+		// mode: Boolean: true/false or "absolute"/"relative" to specify the mode
 		this.absolute = typeof(mode) == "string" ? (mode == "absolute") : mode;
 		return this; // self
 	},
 	getAbsoluteMode: function(){
 		// summary: returns a current value of the absolute mode
 		return this.absolute; // Boolean
 	},
+	
 	getBoundingBox: function(){
-		// summary: returns a bounding box {x, y, width, height} or null
-		return "l" in this.bbox ? {x: this.bbox.l, y: this.bbox.t, width: this.bbox.r - this.bbox.l, height: this.bbox.b - this.bbox.t} : null; // Object
+		// summary: returns the bounding box {x, y, width, height} or null
+		return "l" in this.bbox ? {x: this.bbox.l, y: this.bbox.t, width: this.bbox.r - this.bbox.l, height: this.bbox.b - this.bbox.t} : null; // dojo.gfx.Rectangle
 	},
+	
 	getLastPosition: function(){
 		// summary: returns the last point in the path, or null
 		return "x" in this.last ? this.last : null; // Object
 	},
 	
 	// segment interpretation
-	_updateBBox: function(/* Number */ x, /* Number */ y){
-		// summary: updates a bounding box of path with new point
+	_updateBBox: function(x, y){
+		// summary: updates the bounding box of path with new point
+		// x: Number: an x coordinate
+		// y: Number: a y coordinate
 		
 		// we use {l, b, r, t} representation of a bbox
 		if("l" in this.bbox){
@@ -61,8 +65,9 @@
 			this.bbox = {l: x, b: y, r: x, t: y};
 		}
 	},
-	_updateWithSegment: function(/* Object */ segment){
-		// summary: updates a bounding box of path with new segment
+	_updateWithSegment: function(segment){
+		// summary: updates the bounding box of path with new segment
+		// segment: Object: a segment
 		var n = segment.args;
 		var l = n.length;
 		// update internal variables: bbox, absolute, last
@@ -166,12 +171,14 @@
 			this.shape.path = this.shape.path.concat(path);
 		}
 	},
+	
 	// a dictionary, which maps segment type codes to a number of their argemnts
 	_validSegments: {m: 2, l: 2, h: 1, v: 1, c: 6, s: 4, q: 4, t: 2, a: 7, z: 0},
-	_pushSegment: function(/* String */ action, /* Array */ args){
+	
+	_pushSegment: function(action, args){
 		// summary: adds a segment
-		// action: valid SVG code for a segment's type
-		// args: a list of parameters for this segment
+		// action: String: valid SVG code for a segment's type
+		// args: Array: a list of parameters for this segment
 		var group = this._validSegments[action.toLowerCase()];
 		if(typeof(group) == "number"){
 			if(group){
@@ -187,8 +194,11 @@
 			}
 		}
 	},
-	_collectArgs: function(/* Array */ array, /* Array */ args){
+	
+	_collectArgs: function(array, args){
 		// summary: converts an array of arguments to plain numeric values
+		// array: Array: an output argument (array of numbers)
+		// args: Array: an input argument (can be values of Boolean, Number, dojo.gfx.Point, or an embedded array of them)
 		for(var i = 0; i < args.length; ++i){
 			var t = args[i];
 			if(typeof(t) == "boolean"){
@@ -280,6 +290,7 @@
 	// setShape
 	_setPath: function(path){
 		// summary: forms a path using an SVG path string
+		// path: String: an SVG path string
 		var p = path.match(dojo.gfx.pathRegExp);
 		this.segments = [];
 		this.absolute = true;
@@ -306,6 +317,7 @@
 	},
 	setShape: function(newShape){
 		// summary: forms a path using a shape
+		// newShape: Object: an SVG path string or a path object (see dojo.gfx.defaultPath)
 		this.shape = dojo.gfx.makeParameters(this.shape, typeof(newShape) == "string" ? {path: newShape} : newShape);
 		var path = this.shape.path;
 		// switch to non-updating version of path building
@@ -316,5 +328,6 @@
 		return this; // self
 	},
 	
-	_2PI: Math.PI * 2 // useful constant for descendants
+	// useful constant for descendants
+	_2PI: Math.PI * 2
 });