Added convenience functions getLonLatFromPixel and getPixelFromLonLat; added some more jsdoc.

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

lib/OpenLayers/Map.js

@@ -119,6 +119,7 @@ OpenLayers.Map.prototype = {
     },
 
     /**
+    * @private
     */
     destroy:function() {
         if (this.layers != null) {
@@ -264,6 +265,9 @@ OpenLayers.Map.prototype = {
         return this.size;
     },
 
+    /**
+    * @private
+    */
     updateSize: function() {
         this.size = new OpenLayers.Size(
                     this.div.clientWidth, this.div.clientHeight);
@@ -279,6 +283,7 @@ OpenLayers.Map.prototype = {
             this.size.h = parseInt(this.div.style.height);
     	}
     },
+
     /**
     * @return {OpenLayers.LonLat}
     */
@@ -335,6 +340,7 @@ OpenLayers.Map.prototype = {
      * 
      * @returns px translated into view port pixel coordinates
      * @type OpenLayers.Pixel
+     * @private
      */
     getViewPortPxFromLayerPx:function(layerPx) {
         var viewPortPx = layerPx.copyOf();
@@ -350,6 +356,7 @@ OpenLayers.Map.prototype = {
      * 
      * @returns px translated into view port pixel coordinates
      * @type OpenLayers.Pixel
+     * @private
      */
     getLayerPxFromViewPortPx:function(viewPortPx) {
         var layerPx = viewPortPx.copyOf();
@@ -379,6 +386,7 @@ OpenLayers.Map.prototype = {
     *          OpenLayers.Pixel, translated into lon/lat given the 
     *          current extent and resolution
     * @type OpenLayers.LonLat
+    * @private
     */
     getLonLatFromViewPortPx: function (viewPortPx) {
         var center = this.getCenter();        //map center lon/lat
@@ -392,6 +400,19 @@ OpenLayers.Map.prototype = {
                                      center.lat - delta_y * res); 
     },
 
+    // getLonLatFromPixel is a convenience function for the API
+    /**
+    * @param {OpenLayers.Pixel} pixel
+    *
+    * @returns An OpenLayers.LonLat corresponding to the given
+    *          OpenLayers.Pixel, translated into lon/lat using the 
+    *          current extent and resolution
+    * @type OpenLayers.LonLat
+    */
+    getLonLatFromPixel: function (px) {
+	return this.getLonLatFromViewPortPx(px);
+    },
+
     /**
     * @param {OpenLayers.LonLat} lonlat
     *
@@ -413,6 +434,7 @@ OpenLayers.Map.prototype = {
     *          translated into view port pixels given the current extent 
     *          and resolution
     * @type OpenLayers.Pixel
+    * @private
     */
     getViewPortPxFromLonLat: function (lonlat) {
         var resolution = this.getResolution();
@@ -423,6 +445,19 @@ OpenLayers.Map.prototype = {
                        );    
     },
 
+    // getLonLatFromPixel is a convenience function for the API
+    /**
+    * @param {OpenLayers.LonLat} lonlat
+    *
+    * @returns An OpenLayers.Pixel corresponding to the OpenLayers.LonLat
+    *          translated into view port pixels using the current extent 
+    *          and resolution
+    * @type OpenLayers.Pixel
+    */
+    getPixelFromLonLat: function (lonlat) {
+	return this.getViewPortPxFromLonLat(lonlat);
+    },
+
     /**
     * @param {OpenLayers.LonLat} lonlat
     * @param {int} zoom
@@ -446,8 +481,8 @@ OpenLayers.Map.prototype = {
     
     /**
      * ZOOM TO BOUNDS FUNCTION
+     * @private
      */
-
     moveToNewExtent: function (zoomChanged) {
         if (zoomChanged != null) { // reset the layerContainerDiv's location
             this.layerContainerDiv.style.left = "0px";
@@ -472,17 +507,18 @@ OpenLayers.Map.prototype = {
     /**
      * zoomIn
      * Increase zoom level by one.
+     * @param {int} zoom
      */
     zoomIn: function() {
         if (this.zoom != null && this.zoom <= this.getZoomLevels()) {
             this.zoomTo( this.zoom += 1 );
         }
-        
     },
     
     /**
      * zoomTo
      * Set Zoom To int
+     * @param {int} zoom
      */
     zoomTo: function(zoom) {
        if (zoom >= 0 && zoom <= this.getZoomLevels()) {
@@ -495,6 +531,7 @@ OpenLayers.Map.prototype = {
     /**
      * zoomOut
      * Decrease zoom level by one.
+     * @param {int} zoom
      */
     zoomOut: function() {
         if (this.zoom != null && this.zoom > 0) {
@@ -502,6 +539,10 @@ OpenLayers.Map.prototype = {
         }
     },
     
+    /**
+     * zoomExtent
+     * Zoom to the full extent and recenter.
+     */
     zoomExtent: function() {
         var fullExtent = this.getFullExtent();
         var oldZoom = this.zoom;
@@ -514,6 +555,7 @@ OpenLayers.Map.prototype = {
 
     /**
     * @param {OpenLayers.LonLat} lonlat
+    * @private
     */
     moveLayerContainer: function (lonlat) {
         var container = this.layerContainerDiv;