more doc comments for the drag handler

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

lib/OpenLayers/Handler/Drag.js

@@ -4,9 +4,24 @@
 
 /**
  * @requires OpenLayers/Handler.js
- * @requires OpenLayers/Events.js
  * 
  * Class: OpenLayers.Handler.Drag
+ * The drag handler is used to deal with sequences of browser events related
+ *     to dragging.  The handler is used by controls that want to know when
+ *     a drag sequence begins, when a drag is happening, and when it has
+ *     finished.
+ *
+ * Controls that use the drag handler typically construct it with callbacks
+ *     for 'down', 'move', and 'done'.  Callbacks for these keys are called
+ *     when the drag begins, with each move, and when the drag is done.  In
+ *     addition, controls can have callbacks keyed to 'up' and 'out' if they
+ *     care to differentiate between the types of events that correspond with
+ *     the end of a drag sequence.
+ *
+ * Create a new drag handler with the <OpenLayers.Handler.Drag> constructor.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Handler>
  */
 OpenLayers.Handler.Drag = OpenLayers.Class.create();
 OpenLayers.Handler.Drag.prototype = 
@@ -15,7 +30,7 @@ OpenLayers.Handler.Drag.prototype =
     /** 
      * Property: started
      * {Boolean} When a mousedown event is received, we want to record it, but
-     *           not set 'dragging' until the mouse moves after starting. 
+     *     not set 'dragging' until the mouse moves after starting. 
      */
     started: false,
     
@@ -42,20 +57,27 @@ OpenLayers.Handler.Drag.prototype =
      * Returns OpenLayers.Handler.Drag
      * 
      * Parameters:
-     * control - {<OpenLayers.Control>} 
+     * control - {<OpenLayers.Control>} The control that is making use of
+     *     this handler.  If a handler is being used without a control, the
+     *     handlers setMap method must be overridden to deal properly with
+     *     the map.
      * callbacks - {Object} An object containing a single function to be
-     *                      called when the drag operation is finished.
+     *     called when the drag operation is finished. The callback should
-     *                      The callback should expect to recieve a single
+     *     expect to recieve a single argument, the pixel location of the event.
-     *                      argument, the pixel location of the event.
+     *     Callbacks for 'move' and 'done' are supported. You can also speficy
-     *                      Callbacks for 'move' and 'done' are supported. 
+     *     callbacks for 'down', 'up', and 'out' to respond to those events.
-     *                      You can also speficy callbacks for 'down', 'up', 
-     *                      and 'out' to respond to those events.
      * options - {Object} 
      */
     initialize: function(control, callbacks, options) {
         OpenLayers.Handler.prototype.initialize.apply(this, arguments);
     },
     
+    /**
+     * The methods below are part of the magic of event handling.  Because
+     *     they are named like browser events, they are registered as listeners
+     *     for the events they represent.
+     */
+
     /**
      * Method: mousedown
      * Handle mousedown events
@@ -63,7 +85,8 @@ OpenLayers.Handler.Drag.prototype =
      * Parameters:
      * evt - {Event} 
      *
-     * Return: {Boolean} Should the event propagate
+     * Return:
+     * {Boolean} Let the event propagate.
      */
     mousedown: function (evt) {
         if (this.checkModifiers(evt) && OpenLayers.Event.isLeftClick(evt)) {
@@ -86,7 +109,8 @@ OpenLayers.Handler.Drag.prototype =
      * Parameters:
      * evt - {Event} 
      *
-     * Return: {Boolean} Should the event propagate
+     * Return:
+     * {Boolean} Let the event propagate.
      */
     mousemove: function (evt) {
         if (this.started) {
@@ -107,7 +131,8 @@ OpenLayers.Handler.Drag.prototype =
      * Parameters:
      * evt - {Event} 
      *
-     * Return: {Boolean} Should the event propagate
+     * Return:
+     * {Boolean} Let the event propagate.
      */
     mouseup: function (evt) {
         if (this.started) {
@@ -128,7 +153,8 @@ OpenLayers.Handler.Drag.prototype =
      * Parameters:
      * evt - {Event} 
      *
-     * Return: {Boolean} Should the event propagate
+     * Return:
+     * {Boolean} Let the event propagate.
      */
     mouseout: function (evt) {
         if (this.started && OpenLayers.Util.mouseLeft(evt, this.map.div)) {
@@ -154,7 +180,8 @@ OpenLayers.Handler.Drag.prototype =
      * Parameters: 
      * evt - {Event} 
      * 
-     * Return: {Boolean} Should the event propagate
+     * Return:
+     * {Boolean} Let the event propagate.
      */
     click: function (evt) {
         // throw away the first left click event that happens after a mouse up
@@ -170,8 +197,8 @@ OpenLayers.Handler.Drag.prototype =
      * Method: activate
      * Activate the handler.
      * 
-     * Return: {Boolean} Was activation successful.  
+     * Return:
-     *                   Returns false if already active.
+     * {Boolean} The handler was successfully activated.
      */
     activate: function() {
         if(OpenLayers.Handler.prototype.activate.apply(this, arguments)) {
@@ -186,8 +213,8 @@ OpenLayers.Handler.Drag.prototype =
      * Method: deactivate 
      * Deactivate the handler.
      * 
-     * Return: {Boolean} Was deactivation successful.  
+     * Return:
-     *                   Returns false if already active.
+     * {Boolean} The handler was successfully deactivated.
      */
     deactivate: function() {
         if(OpenLayers.Handler.prototype.deactivate.apply(this, arguments)) {