adding in some docs for the Handler base class

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

lib/OpenLayers/Handler.js

@@ -4,10 +4,27 @@
 
 
 /**
+ * @requires OpenLayers/Events.js
+ * 
  * Class: OpenLayers.Handler
- * Base class to construct a higher-level handler for event sequences.
+ * Base class to construct a higher-level handler for event sequences.  All
+ *     handlers have activate and deactivate methods.  In addition, they have
+ *     methods named like browser events.  When a handler is activated, any
+ *     additional methods named like a browser event is registered as a
+ *     listener for the corresponding event.  When a handler is deactivated,
+ *     those same methods are unregistered as event listeners.
+ *
+ * Handlers also typically have a callbacks object with keys named like
+ *     the abstracted events or event sequences that they are in charge of
+ *     handling.  The controls that wrap handlers define the methods that
+ *     correspond to these abstract events - so instead of listening for
+ *     individual browser events, they only listen for the abstract events
+ *     defined by the handler.
+ *     
  * Handlers are created by controls, which ultimately have the responsibility
- * of making changes to the map.
+ *     of making changes to the the state of the application.  Handlers
+ *     themselves may make temporary changes, but in general are expected to
+ *     return the application in the same state that they found it.
  */
 OpenLayers.Handler = OpenLayers.Class.create();
 
@@ -24,9 +41,10 @@ OpenLayers.Handler.prototype = {
     id: null,
         
     /**
-     * Property: control
+     * APIProperty: control
-     * {<OpenLayers.Control>}. The control that initialized this
+     * {<OpenLayers.Control>}. The control that initialized this handler.  The
-     * handler.
+     *     control is assumed to have a valid map property - that map is used
+     *     in the handler's own setMap method.
      */
     control: null,
 
@@ -53,9 +71,15 @@ OpenLayers.Handler.prototype = {
      * Construct a handler.
      *
      * Parameters:
-     * control - {<OpenLayers.Control>} 
+     * control - {<OpenLayers.Control>} The control that initialized this
-     * callbacks - {Object} A hash of callback functions
+     *     handler.  The control is assumed to have a valid map property; that
-     * options - {Object} 
+     *     map is used in the handler's own setMap method.
+     * callbacks - {Object} An object whose properties correspond to abstracted
+     *     events or sequences of browser events.  The values for these
+     *     properties are functions defined by the control that get called by
+     *     the handler.
+     * options - {Object} An optional object whose properties will be set on
+     *     the handler.
      */
     initialize: function(control, callbacks, options) {
         OpenLayers.Util.extend(this, options);
@@ -96,11 +120,11 @@ OpenLayers.Handler.prototype = {
     },
 
     /**
-     * Method: activate
+     * APIMethod: activate
      * Turn on the handler.  Returns false if the handler was already active.
      * 
      * Return: 
-     * {Boolean} 
+     * {Boolean} The handler was activated.
      */
     activate: function() {
         if(this.active) {
@@ -118,10 +142,11 @@ OpenLayers.Handler.prototype = {
     },
     
     /**
-     * Method: deactivate
+     * APIMethod: deactivate
      * Turn off the handler.  Returns false if the handler was already inactive.
      * 
-     * Return: {Boolean}
+     * Return:
+     * {Boolean} The handler was deactivated.
      */
     deactivate: function() {
         if(!this.active) {
@@ -140,7 +165,13 @@ OpenLayers.Handler.prototype = {
 
     /**
     * Method: callback
-    * trigger the control's named callback with the given arguments
+    * Trigger the control's named callback with the given arguments
+    *
+    * Parameters:
+    * name - {String} The key for the callback that is one of the properties
+    *     of the handler's callbacks object.
+    * args - {Array} An array of arguments with which to call the callback
+    *     (defined by the control).
     */
     callback: function (name, args) {
         if (this.callbacks[name]) {
@@ -167,6 +198,7 @@ OpenLayers.Handler.prototype = {
 
     /**
      * Method: destroy
+     * Deconstruct the handler.
      */
     destroy: function () {
         // eliminate circular references