Merge all changes from the naturaldocs sandbox. This brings all the work that

has been done in the NaturalDocs branch back to trunk. Thanks to everyone who
helped out in making this happen. (I could list people, but the list would
be long, and I'm already mentally on vacation.)


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

lib/OpenLayers/Control.js

@@ -3,7 +3,9 @@
  * for the full text of the license. */
 
 /**
-* @class
+* Class: OpenLayers.Control
+* Controls affect the display or behavior of the map. They allow everything
+* from panning and zooming to displaying a scale indicator.
 */
 OpenLayers.Control = OpenLayers.Class.create();
 
@@ -13,40 +15,58 @@ OpenLayers.Control.TYPE_TOOL   = 3;
 
 OpenLayers.Control.prototype = {
 
-    /** @type String */
-    id: null,
+    /** 
+	 * Property: id 
+	 * {String} 
+	 */
+	id: null,
     
-    /** this gets set in the addControl() function in OpenLayers.Map
-    * @type OpenLayers.Map */
-    map: null,
-
-    /** @type DOMElement */
-    div: null,
+    /** 
+	 * Property: map 
+     * {<OpenLayers.Map>} this gets set in the addControl() function in
+     * OpenLayers.Map 
+	 */
+	map: null,
 
     /** 
-     * Controls can have a 'type'. The type determines the type of interactions
-     * which are possible with them when they are placed into a toolbar.
-     * 
-     * @type OpenLayers.Control.TYPES
-     */
-    type: null, 
+	 * Property: div 
+	 * {DOMElement} 
+	 */
+	div: null,
 
-    /**  This property is used for CSS related to the drawing of the Control.
-     * 
-     * @type string 
-     */
-    displayClass: "",
+    /** 
+	 * Property: type 
+     * {OpenLayers.Control.TYPES} Controls can have a 'type'. The type
+     * determines the type of interactions which are possible with them when
+     * they are placed into a toolbar. 
+	 */
+	type: null, 
 
-    /** @type boolean */
-    active: null,
+    /** 
+	 * Property: displayClass 
+     * {string}  This property is used for CSS related to the drawing of the
+     * Control. 
+	 */
+	displayClass: "",
 
-    /** @type OpenLayers.Handler */
-    handler: null,
+    /** 
+	 * Property: active 
+	 * {boolean} null
+	 */
+	active: null,
+
+    /** 
+	 * Property: handler 
+	 * {<OpenLayers.Handler}> null
+	 */
+	handler: null,
 
     /**
-     * @constructor
+     * Constructor: OpenLayers.Control
+     * Create an OpenLayers Control.
      * 
-     * @param {Object} options
+     * Parameters:
+     * options - {Object} 
      */
     initialize: function (options) {
         // We do this before the extend so that instances can override
@@ -60,7 +80,7 @@ OpenLayers.Control.prototype = {
     },
 
     /**
-     * 
+     * Method: destroy
      */
     destroy: function () {
         // eliminate circular references
@@ -70,11 +90,14 @@ OpenLayers.Control.prototype = {
         this.map = null;
     },
 
-    /** Set the map property for the control. This is done through an accessor
+    /** 
+     * 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. 
-     * 
-     * @param {OpenLayers.Map} map
+     *
+     * Parameters:
+     * map - {<OpenLayers.Map>} 
      */
     setMap: function(map) {
         this.map = map;
@@ -84,10 +107,13 @@ OpenLayers.Control.prototype = {
     },
   
     /**
-     * @param {OpenLayers.Pixel} px
+     * Method: draw 
      *
-     * @returns A reference to the DIV DOMElement containing the control
-     * @type DOMElement
+     * Parameters:
+     * px - {<OpenLayers.Pixel>} 
+     *
+     * Return:
+     * {DOMElement} A reference to the DIV DOMElement containing the control
      */
     draw: function (px) {
         if (this.div == null) {
@@ -103,7 +129,10 @@ OpenLayers.Control.prototype = {
     },
 
     /**
-     * @param {OpenLayers.Pixel} px
+     * Method: moveTo
+     *
+     * Parameters:
+     * px - {<OpenLayers.Pixel>}
      */
     moveTo: function (px) {
         if ((px != null) && (this.div != null)) {
@@ -113,7 +142,10 @@ OpenLayers.Control.prototype = {
     },
 
     /**
-     * @type boolean
+     * Method: activate
+     * 
+     * Return:
+     * {Boolean}
      */
     activate: function () {
         if (this.active) {
@@ -127,7 +159,10 @@ OpenLayers.Control.prototype = {
     },
     
     /**
-     * @type boolean
+     * Method: deactivate
+     * 
+     * Return:
+     * {Boolean}
      */
     deactivate: function () {
         if (this.active) {