From dfa4441646b64d73806381451ae9970adec4490d Mon Sep 17 00:00:00 2001
From: euzuro <euzuro@metacarta.com>
Date: Mon, 2 Apr 2007 22:49:13 +0000
Subject: [PATCH] step one of cleaning up events.js: jsdoc

git-svn-id: http://svn.openlayers.org/trunk/openlayers@2981 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf
---
 lib/OpenLayers/Events.js | 100 +++++++++++++++++++++++++++++++++------
 1 file changed, 86 insertions(+), 14 deletions(-)

diff --git a/lib/OpenLayers/Events.js b/lib/OpenLayers/Events.js
index 1e752b39ba..3b42d9b96d 100644
--- a/lib/OpenLayers/Events.js
+++ b/lib/OpenLayers/Events.js
@@ -2,39 +2,91 @@
  * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt 
  * for the full text of the license. */
 
-/* @requires OpenLayers/Util.js
+/**
+ *  @requires OpenLayers/Util.js
+ * 
+ *  @class (Not really a class, but kind of)
+ * 
  */
-
 OpenLayers.Event = {
-  KEY_BACKSPACE: 8,
-  KEY_TAB:       9,
-  KEY_RETURN:   13,
-  KEY_ESC:      27,
-  KEY_LEFT:     37,
-  KEY_UP:       38,
-  KEY_RIGHT:    39,
-  KEY_DOWN:     40,
-  KEY_DELETE:   46,
 
+  /** @final @type int */
+  KEY_BACKSPACE: 8,
+
+  /** @final @type int */
+  KEY_TAB: 9,
+
+  /** @final @type int */
+  KEY_RETURN: 13,
+
+  /** @final @type int */
+  KEY_ESC: 27,
+
+  /** @final @type int */
+  KEY_LEFT: 37,
+
+  /** @final @type int */
+  KEY_UP: 38,
+
+  /** @final @type int */
+  KEY_RIGHT: 39,
+
+  /** @final @type int */
+  KEY_DOWN: 40,
+
+  /** @final @type int */
+  KEY_DELETE: 46,
+
+
+  /**
+   * @param {Event} event
+   * 
+   * @returns The element that caused the alert
+   * @type DOMElement
+   */
   element: function(event) {
     return event.target || event.srcElement;
   },
 
+  /**
+   * @param {Event} event
+   * 
+   * @returns Whether or not the event was the result of a left click
+   * @type boolean
+   */
   isLeftClick: function(event) {
     return (((event.which) && (event.which == 1)) ||
             ((event.button) && (event.button == 1)));
   },
 
+  /**
+   * @param {Event} event
+   * 
+   * @returns
+   * @type int
+   */
   pointerX: function(event) {
     return event.pageX || (event.clientX +
       (document.documentElement.scrollLeft || document.body.scrollLeft));
   },
 
+  /**
+   * @param {Event} event
+   * 
+   * @returns
+   * @type int
+   */
   pointerY: function(event) {
     return event.pageY || (event.clientY +
       (document.documentElement.scrollTop || document.body.scrollTop));
   },
 
+  /** Stops an event from propagating. If the event's 'preventDefault' 
+   *   property is set, then we prevent the default browser behaviour
+   *   (such as text selection, radio-button clicking, etc) from occurring
+   * 
+   * @param {Event} event
+   */
   stop: function(event) {
     if (event.preventDefault) {
       event.preventDefault();
@@ -45,8 +97,14 @@ OpenLayers.Event = {
     }
   },
 
-  // find the first node with the given tagName, starting from the
-  // node the event was triggered on; traverses the DOM upwards
+  /** 
+   * @param {Event} event
+   * @param {String} tagName
+   * 
+   * @returns The first node with the given tagName, starting from the node 
+   *           the event was triggered on and traversing the DOM upwards
+   * @type DOMElement
+   */
   findElement: function(event, tagName) {
     var element = OpenLayers.Event.element(event);
     while (element.parentNode && (!element.tagName ||
@@ -55,12 +113,19 @@ OpenLayers.Event = {
     return element;
   },
 
-  /** A hashtable cach of the event observers, keyed by element.id
+  /** A hashtable cache of the event observers, keyed by element.id
    * 
    * @type Object
    */
   observers: false,
 
+  /** 
+   * @param {DOMElement} element
+   * @param {String} name
+   * @param {function} observer
+   * @param {Boolean} useCapture
+   * 
+   */
   _observeAndCache: function(element, name, observer, useCapture) {
     if (!this.observers) this.observers = new Object();
 
@@ -123,6 +188,13 @@ OpenLayers.Event = {
         OpenLayers.Event.observers = false;
     },
 
+  /** 
+   * @param {DOMElement || String} elementParam
+   * @param {String} name
+   * @param {function} observer
+   * @param {Boolean} useCapture
+   * 
+   */
   observe: function(elementParam, name, observer, useCapture) {
     var element = OpenLayers.Util.getElement(elementParam);
     useCapture = useCapture || false;