adding comments, coding standards, jsdoc

git-svn-id: http://svn.openlayers.org/trunk/openlayers@862 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/Events.js

@@ -31,20 +31,24 @@ OpenLayers.Events.prototype = {
     /**
      * @constructor 
      * 
-     * @param {OpenLayers.Map} map
+     * @param {OpenLayers.Map} object The js object to which this Events object
-     * @param {DOMElement} div
+     *                                is being added
+     * @param {DOMElement} div A dom element to respond to browser events
+     * @param {Array} eventTypes Array of custom application events
      */
     initialize: function (object, div, eventTypes) {
         this.listeners  = {};
         this.object     = object;
         this.div        = div;
         this.eventTypes = eventTypes;
+
         if (eventTypes) {
             for (var i = 0; i < this.eventTypes.length; i++) {
                 // create a listener list for every custom application event
                 this.listeners[ this.eventTypes[i] ] = [];
             }
         }
+
         for (var i = 0; i < this.BROWSER_EVENTS.length; i++) {
             var eventType = this.BROWSER_EVENTS[i];
 
@@ -55,14 +59,15 @@ OpenLayers.Events.prototype = {
             Event.observe(div, eventType, 
                 this.handleBrowserEvent.bindAsEventListener(this));
         }
+
         // disable dragstart in IE so that mousedown/move/up works normally
         Event.observe(div, "dragstart", Event.stop);
     },
 
     /**
-     * @param {str} type
+     * @param {String} type Name of the event to register
-     * @param {Object} obj
+     * @param {Object} obj The object to bind the context to for the callback
-     * @param {Function} func
+     * @param {Function} func The callback function
      */
     register: function (type, obj, func) {
         if (func == null) {
@@ -74,7 +79,7 @@ OpenLayers.Events.prototype = {
     },
     
     /**
-     * @param {str} type
+     * @param {String} type
      * @param {Object} obj
      * @param {Function} func
      */
@@ -89,38 +94,16 @@ OpenLayers.Events.prototype = {
     },
 
     /**
-     * @param {str} type
+     * @param {String} type
      */
     remove: function(type) {
         this.listeners[type].pop();
     },
 
-    /**
+    /** Trigger a specified registered event
-     * @param {event} evt
-     */
-    handleBrowserEvent: function (evt) {
-        evt.xy = this.getMousePosition(evt); 
-        this.triggerEvent(evt.type, evt)
-    },
-
-    /**
-     * @param {event} evt
      * 
-     * @returns The current xy coordinate of the mouse, adjusted for offsets
+     * @param {String} type
-     * @type OpenLayers.Pixel
+     * @param {Event} evt
-     */
-    getMousePosition: function (evt) {
-        if (!this.div.offsets) {
-            this.div.offsets = Position.page(this.div);
-        }
-        return new OpenLayers.Pixel(
-                        evt.clientX - this.div.offsets[0], 
-                        evt.clientY - this.div.offsets[1]); 
-    },
-
-    /**
-     * @param {str} type
-     * @param {event} evt
      */
     triggerEvent: function (type, evt) {
         if (evt == null) {
@@ -135,5 +118,38 @@ OpenLayers.Events.prototype = {
             var continueChain = callback.func.call(callback.obj, evt);
             if (continueChain != null && !continueChain) break;
         }
-    }
+    },
+
+    /** Basically just a wrapper to the triggerEvent() function, but takes 
+     *   care to set a property 'xy' on the event with the current mouse 
+     *   position.
+     * 
+     * @private
+     * 
+     * @param {event} evt
+     */
+    handleBrowserEvent: function (evt) {
+        evt.xy = this.getMousePosition(evt); 
+        this.triggerEvent(evt.type, evt)
+    },
+
+    /**
+     * @private 
+     * 
+     * @param {event} evt
+     * 
+     * @returns The current xy coordinate of the mouse, adjusted for offsets
+     * @type OpenLayers.Pixel
+     */
+    getMousePosition: function (evt) {
+        if (!this.div.offsets) {
+            this.div.offsets = Position.page(this.div);
+        }
+        return new OpenLayers.Pixel(
+                        evt.clientX - this.div.offsets[0], 
+                        evt.clientY - this.div.offsets[1]); 
+    },
+
+    /** @final @type String */
+    CLASS_NAME: "OpenLayers.Events"
 };