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/Layer/EventPane.js

@@ -4,42 +4,55 @@
 
 
 /**
- * @class
- * 
  * @requires OpenLayers/Layer.js
  * @requires OpenLayers/Util.js
+ * 
+ * Class: OpenLayers.Layer.EventPane
+ * Base class for 3rd party layers.  Create a new event pane layer with the
+ * <OpenLayers.Layer.EventPane> constructor.
+ * 
+ * Inherits from:
+ *  - <OpenLayers.Layer>
  */
 OpenLayers.Layer.EventPane = OpenLayers.Class.create();
 OpenLayers.Layer.EventPane.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Layer, {
 
-    /** EventPaned layers are always base layers, by necessity.
-     * 
-     * @type Boolean */
+    /**
+     * Property: isBaseLayer
+     * {Boolean} EventPaned layers are always base layers, by necessity.
+     */ 
     isBaseLayer: true,
 
-    /** EventPaned layers are fixed by default.
-     * 
-     * @type Boolean */
+    /**
+     * APIProperty: isFixed
+     * {Boolean} EventPaned layers are fixed by default.
+     */ 
     isFixed: true,
 
-    /** @type DOMElement */
+    /**
+     * Property: pane
+     * {DOMElement} A reference to the element that controls the events.
+     */
     pane: null,
 
 
-    /** This is the object which will be used to load the 3rd party library
-     *   in the case of the google layer, this will be of type GMap, 
-     *   in the case of the ve layer, this will be of type VEMap
-     * 
-     * @type Object */
+    /**
+     * Property: mapObject
+     * {Object} This is the object which will be used to load the 3rd party library
+     * in the case of the google layer, this will be of type GMap, 
+     * in the case of the ve layer, this will be of type VEMap
+     */ 
     mapObject: null,
 
 
     /**
-     * @constructor
-     * 
-     * @param {String} name
-     * @param {Object} options Hashtable of extra options to tag onto the layer
+     * Constructor: OpenLayers.Layer.EventPane
+     * Create a new event pane layer
+     *
+     * Parameters:
+     * name - {String}
+     * options - {Object} Hashtable of extra options to tag onto the layer
      */
     initialize: function(name, options) {
         OpenLayers.Layer.prototype.initialize.apply(this, arguments);
@@ -49,7 +62,8 @@ OpenLayers.Layer.EventPane.prototype =
     },
     
     /**
-     * 
+     * APIMethod: destroy
+     * Deconstruct this layer.
      */
     destroy: function() {
         this.mapObject = null;
@@ -57,11 +71,14 @@ OpenLayers.Layer.EventPane.prototype =
     },
 
     
-    /** Set the map property for the layer. 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
+    /**
+     * Method: setMap
+     * Set the map property for the layer. This is done through an accessor
+     * so that subclasses can override this and take special action once 
+     * they have their map variable set. 
+     *
+     * Parameters:
+     * map - {<OpenLayers.Map>}
      */
     setMap: function(map) {
         OpenLayers.Layer.prototype.setMap.apply(this, arguments);
@@ -90,11 +107,10 @@ OpenLayers.Layer.EventPane.prototype =
         }
     },
   
-    /** If we can't load the GMap, then display an error message to the 
-     *   user and tell them where to go for help.
-     * 
-     * @private
-     * 
+    /**
+     * Method: loadWarningMessage
+     * If we can't load the map lib, then display an error message to the 
+     * user and tell them where to go for help.
      */
     loadWarningMessage:function() {
 
@@ -126,8 +142,12 @@ OpenLayers.Layer.EventPane.prototype =
     },
   
   
-    /** 
-     * @param {Boolean} display
+    /**
+     * Method: display
+     * Set the display on the pane
+     *
+     * Parameters:
+     * display - {Boolean}
      */
     display: function(display) {
         OpenLayers.Layer.prototype.display.apply(this, arguments);
@@ -135,17 +155,25 @@ OpenLayers.Layer.EventPane.prototype =
     },
   
     /**
-     * @param {int} zIndex
+     * Method: setZIndex
+     * Set the z-index order for the pane.
+     * 
+     * Parameters:
+     * zIndex - {int}
      */
     setZIndex: function (zIndex) {
         OpenLayers.Layer.prototype.setZIndex.apply(this, arguments);
         this.pane.style.zIndex = parseInt(this.div.style.zIndex) + 1;
     },
 
-    /** 
-     * @param {OpenLayers.Bounds} bounds
-     * @param {Boolean} zoomChanged
-     * @param {Boolean} dragging
+    /**
+     * Method: moveTo
+     * Handle calls to move the layer.
+     * 
+     * Parameters:
+     * bounds - {<OpenLayers.Bounds>}
+     * zoomChanged - {Boolean}
+     * dragging - {Boolean}
      */
     moveTo:function(bounds, zoomChanged, dragging) {
         OpenLayers.Layer.prototype.moveTo.apply(this, arguments);
@@ -182,12 +210,16 @@ OpenLayers.Layer.EventPane.prototype =
   /********************************************************/
 
     /**
-     * @param {OpenLayers.Pixel} viewPortPx
+     * Method: getLonLatFromViewPortPx
+     * Get a map location from a pixel location
+     * 
+     * Parameters:
+     * viewPortPx - {<OpenLayers.Pixel>}
      *
-     * @returns An OpenLayers.LonLat which is the passed-in view port
-     *          OpenLayers.Pixel, translated into lon/lat by GMAPS
-     *          If gmap is not loaded or not centered, returns null
-     * @type OpenLayers.LonLat
+     * Return:
+     *  {<OpenLayers.LonLat>} An OpenLayers.LonLat which is the passed-in view
+     *  port OpenLayers.Pixel, translated into lon/lat by map lib
+     *  If the map lib is not loaded or not centered, returns null
      */
     getLonLatFromViewPortPx: function (viewPortPx) {
         var lonlat = null;
@@ -202,12 +234,16 @@ OpenLayers.Layer.EventPane.prototype =
 
  
     /**
-     * @param {OpenLayers.LonLat} lonlat
+     * Method: getViewPortPxFromLonLat
+     * Get a pixel location from a map location
      *
-     * @returns An OpenLayers.Pixel which is the passed-in OpenLayers.LonLat, 
-     *          translated into view port pixels BY GMAPS
-     *          If gmap is not loaded or not centered, returns null
-     * @type OpenLayers.Pixel
+     * Parameters:
+     * lonlat - {<OpenLayers.LonLat>}
+     *
+     * Return:
+     * {<OpenLayers.Pixel>} An OpenLayers.Pixel which is the passed-in
+     * OpenLayers.LonLat, translated into view port pixels by map lib
+     * If map lib is not loaded or not centered, returns null
      */
     getViewPortPxFromLonLat: function (lonlat) {
         var viewPortPx = null;
@@ -236,12 +272,16 @@ OpenLayers.Layer.EventPane.prototype =
   //
 
     /**
-     * @param {Object} moLonLat
+     * Method: getOLLonLatFromMapObjectLonLat
+     * Get an OL style map location from a 3rd party style map location
+     *
+     * Parameters
+     * moLonLat - {Object}
      * 
-     * @returns An OpenLayers.LonLat, translated from the passed in 
+     * Return:
+     * {<OpenLayers.LonLat>} An OpenLayers.LonLat, translated from the passed in 
      *          MapObject LonLat
      *          Returns null if null value is passed in
-     * @type OpenLayers.LonLat
      */
     getOLLonLatFromMapObjectLonLat: function(moLonLat) {
         var olLonLat = null;
@@ -254,12 +294,16 @@ OpenLayers.Layer.EventPane.prototype =
     },
 
     /**
-     * @param {OpenLayers.LonLat} olLonLat
+     * Method: getMapObjectLonLatFromOLLonLat
+     * Get a 3rd party map location from an OL map location.
+     *
+     * Parameters:
+     * olLonLat - {<OpenLayers.LonLat>}
      * 
-     * @returns A MapObject LonLat, translated from the passed in 
+     * Return:
+     * {Object} A MapObject LonLat, translated from the passed in 
      *          OpenLayers.LonLat
      *          Returns null if null value is passed in
-     * @type Object
      */
     getMapObjectLonLatFromOLLonLat: function(olLonLat) {
         var moLatLng = null;
@@ -276,12 +320,16 @@ OpenLayers.Layer.EventPane.prototype =
   //
 
     /**
-     * @param {Object} moPixel
+     * Method: getOLPixelFromMapObjectPixel
+     * Get an OL pixel location from a 3rd party pixel location.
+     *
+     * Parameters:
+     * moPixel - {Object}
      * 
-     * @returns An OpenLayers.Pixel, translated from the passed in 
+     * Return:
+     * {<OpenLayers.Pixel>} An OpenLayers.Pixel, translated from the passed in 
      *          MapObject Pixel
      *          Returns null if null value is passed in
-     * @type OpenLayers.Pixel
      */
     getOLPixelFromMapObjectPixel: function(moPixel) {
         var olPixel = null;
@@ -294,12 +342,16 @@ OpenLayers.Layer.EventPane.prototype =
     },
 
     /**
-     * @param {OpenLayers.Pixel} olPixel
+     * Method: getMapObjectPixelFromOLPixel
+     * Get a 3rd party pixel location from an OL pixel location
+     *
+     * Parameters:
+     * olPixel - {<OpenLayers.Pixel>}
      * 
-     * @returns A MapObject Pixel, translated from the passed in 
+     * Return:
+     * {Object} A MapObject Pixel, translated from the passed in 
      *          OpenLayers.Pixel
      *          Returns null if null value is passed in
-     * @type Object
      */
     getMapObjectPixelFromOLPixel: function(olPixel) {
         var moPixel = null;
@@ -309,6 +361,9 @@ OpenLayers.Layer.EventPane.prototype =
         return moPixel;
     },
 
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} Name of this class
+     */
     CLASS_NAME: "OpenLayers.Layer.EventPane"
 });