Documentation improvements provided by Glen Stampoultzis. (Thanks Glen!) Closes

#825, #836.


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

lib/OpenLayers/Control.js

@@ -3,10 +3,52 @@
  * for the full text of the license. */
 
 /**
-* Class: OpenLayers.Control
-* Controls affect the display or behavior of the map. They allow everything
-* from panning and zooming to displaying a scale indicator.
-*/
+ * Class: OpenLayers.Control
+ * Controls affect the display or behavior of the map. They allow everything
+ * from panning and zooming to displaying a scale indicator. Controls by 
+ * default are added to the map they are contained within however it is
+ * possible to add a control to an external div by passing the div in the
+ * options parameter.
+ * 
+ * Example:
+ * The following example shows how to add many of the common controls
+ * to a map.
+ * 
+ * > var map = new OpenLayers.Map('map', { controls: [] });
+ * >
+ * > map.addControl(new OpenLayers.Control.PanZoomBar());
+ * > map.addControl(new OpenLayers.Control.MouseToolbar());
+ * > map.addControl(new OpenLayers.Control.LayerSwitcher({'ascending':false}));
+ * > map.addControl(new OpenLayers.Control.Permalink());
+ * > map.addControl(new OpenLayers.Control.Permalink('permalink'));
+ * > map.addControl(new OpenLayers.Control.MousePosition());
+ * > map.addControl(new OpenLayers.Control.OverviewMap());
+ * > map.addControl(new OpenLayers.Control.KeyboardDefaults());
+ *
+ * The next code fragment is a quick example of how to intercept 
+ * shift-mouse click to display the extent of the bounding box
+ * dragged out by the user.  Usually controls are not created
+ * in exactly this manner.  See the source for a more complete 
+ * example:
+ *
+ * > var control = new OpenLayers.Control();
+ * > OpenLayers.Util.extend(control, {
+ * >     draw: function () {
+ * >         // this Handler.Box will intercept the shift-mousedown
+ * >         // before Control.MouseDefault gets to see it
+ * >         this.box = new OpenLayers.Handler.Box( control, 
+ * >             {"done": this.notice},
+ * >             {keyMask: OpenLayers.Handler.MOD_SHIFT});
+ * >         this.box.activate();
+ * >     },
+ * >
+ * >     notice: function (bounds) {
+ * >         alert(bounds);
+ * >     }
+ * > }); 
+ * > map.addControl(control);
+ * 
+ */
 OpenLayers.Control = OpenLayers.Class.create();
 
 OpenLayers.Control.TYPE_BUTTON = 1;
@@ -63,7 +105,12 @@ OpenLayers.Control.prototype = {
 
     /**
      * Constructor: OpenLayers.Control
-     * Create an OpenLayers Control.
+     * Create an OpenLayers Control.  The options passed as a parameter
+     * directly extend the control.  For example passing the following:
+     * 
+     * > var control = new OpenLayers.Control({div: myDiv});
+     *
+     * Overrides the default div attribute value of null.
      * 
      * Parameters:
      * options - {Object} 
@@ -81,6 +128,9 @@ OpenLayers.Control.prototype = {
 
     /**
      * Method: destroy
+     * The destroy method is used to perform any clean up before the control
+     * is dereferenced.  Typically this is where event listeners are removed
+     * to prevent memory leaks.
      */
     destroy: function () {
         // eliminate circular references
@@ -93,8 +143,8 @@ OpenLayers.Control.prototype = {
     /** 
      * Method: setMap
      * Set the map property for the control. This is done through an accessor
-     *   so that subclasses can override this and take special action once 
-     *   they have their map variable set. 
+     * so that subclasses can override this and take special action once 
+     * they have their map variable set. 
      *
      * Parameters:
      * map - {<OpenLayers.Map>} 
@@ -107,10 +157,15 @@ OpenLayers.Control.prototype = {
     },
   
     /**
-     * Method: draw 
+     * Method: draw
+     * The draw method is called when the control is ready to be displayed
+     * on the page.  If a div has not been created one is created.  Controls
+     * with a visual component will almost always want to override this method 
+     * to customize the look of control. 
      *
      * Parameters:
-     * px - {<OpenLayers.Pixel>} 
+     * px - {<OpenLayers.Pixel>} The top-left pixel position of the control
+     *      or null.
      *
      * Return:
      * {DOMElement} A reference to the DIV DOMElement containing the control
@@ -130,6 +185,8 @@ OpenLayers.Control.prototype = {
 
     /**
      * Method: moveTo
+     * Sets the left and top style attributes to the passed in pixel 
+     * coordinates.
      *
      * Parameters:
      * px - {<OpenLayers.Pixel>}
@@ -143,9 +200,13 @@ OpenLayers.Control.prototype = {
 
     /**
      * Method: activate
+     * Explicitly activates a control and it's associated
+     * handler if one has been set.  Controls can be
+     * deactivated by calling the deactivate() method.
      * 
      * Return:
-     * {Boolean}
+     * {Boolean}  True if the control was successfully activated or
+     *            false if the control was already active.
      */
     activate: function () {
         if (this.active) {
@@ -160,9 +221,12 @@ OpenLayers.Control.prototype = {
     
     /**
      * Method: deactivate
+     * Deactivates a control and it's associated handler if any.  The exact
+     * effect of this depends on the control itself.
      * 
      * Return:
-     * {Boolean}
+     * {Boolean} True if the control was effectively deactivated or false
+     *           if the control was already inactive.
      */
     deactivate: function () {
         if (this.active) {